fuli-context 0.4.0 → 0.7.2

package/src/external-knowledge/connectors/notion.js

@@ -0,0 +1,307 @@
+const NOTION_API_ROOT = 'https://api.notion.com';
+const NOTION_API_VERSION = '2026-03-11';
+
+export function createNotionConnector({ fetchImpl = globalThis.fetch } = {}) {
+  const request = notionRequester(fetchImpl);
+  return {
+    type: 'notion',
+    name: 'Notion',
+    capabilities: ['discover', 'sync', 'retrieve'],
+
+    async check(context) {
+      notionSources(context.source);
+      const user = await request(context, 'GET', '/v1/users/me');
+      return {
+        status: 'ready',
+        capabilities: ['discover', 'sync', 'retrieve'],
+        account: { id: user.id ?? null, name: user.name ?? null },
+        apiVersion: NOTION_API_VERSION
+      };
+    },
+
+    async discover(context) {
+      const body = {
+        page_size: pageSize(context.limit),
+        filter: { property: 'object', value: 'page' },
+        ...(context.cursor ? { start_cursor: context.cursor } : {}),
+        ...(context.query ? { query: context.query } : {})
+      };
+      const result = await request(context, 'POST', '/v1/search', body);
+      return {
+        items: (result.results ?? []).map(pageSummary),
+        nextCursor: result.next_cursor ?? null,
+        hasMore: result.has_more === true
+      };
+    },
+
+    async sync(context) {
+      const sources = notionSources(context.source);
+      const state = decodeCursor(context.cursor);
+      if (state.sourceIndex >= sources.length) return emptySyncPage();
+      const current = sources[state.sourceIndex];
+      if (current.kind === 'page') {
+        const page = await request(
+          context,
+          'GET',
+          `/v1/pages/${encodeURIComponent(current.id)}`
+        );
+        const nextCursor = nextSourceCursor(state.sourceIndex, sources.length);
+        if (page.in_trash === true) {
+          return {
+            items: [],
+            deleted: [page.id ?? current.id],
+            nextCursor,
+            hasMore: nextCursor !== null
+          };
+        }
+        return {
+          items: [await notionPageDocument(context, request, page)],
+          deleted: [],
+          nextCursor,
+          hasMore: nextCursor !== null
+        };
+      }
+      const query = await request(
+        context,
+        'POST',
+        `/v1/data_sources/${encodeURIComponent(current.id)}/query`,
+        {
+          page_size: pageSize(context.limit),
+          ...(state.startCursor ? { start_cursor: state.startCursor } : {})
+        }
+      );
+      const activePages = (query.results ?? []).filter((page) => page.in_trash !== true);
+      const items = [];
+      for (const page of activePages) {
+        items.push(await notionPageDocument(context, request, page));
+      }
+      const nextCursor = query.has_more === true
+        ? encodeCursor({ sourceIndex: state.sourceIndex, startCursor: query.next_cursor })
+        : nextSourceCursor(state.sourceIndex, sources.length);
+      return {
+        items,
+        deleted: (query.results ?? [])
+          .filter((page) => page.in_trash === true)
+          .map(({ id }) => id),
+        nextCursor,
+        hasMore: nextCursor !== null
+      };
+    },
+
+    async retrieve(context) {
+      const sources = notionSources(context.source);
+      const result = await request(context, 'POST', '/v1/search', {
+        query: requiredString(context.query, 'Notion query'),
+        page_size: pageSize(context.limit),
+        filter: { property: 'object', value: 'page' }
+      });
+      const allowed = (result.results ?? [])
+        .filter((page) => page.in_trash !== true && notionPageIsBound(page, sources))
+        .slice(0, pageSize(context.limit));
+      const items = [];
+      for (const page of allowed) {
+        items.push(await notionPageDocument(context, request, page));
+      }
+      return { items };
+    }
+  };
+}
+
+function notionRequester(fetchImpl) {
+  if (typeof fetchImpl !== 'function') throw new TypeError('Notion fetch is unavailable');
+  return async (context, method, path, body = undefined) => {
+    if (!['GET', 'POST'].includes(method)) {
+      throw new TypeError('Notion connector only permits read operations');
+    }
+    const token = credentialFromEnvironment(context, 'tokenEnv', 'Notion token');
+    const response = await fetchImpl(`${NOTION_API_ROOT}${path}`, {
+      method,
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Notion-Version': NOTION_API_VERSION,
+        Accept: 'application/json',
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' })
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs))
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const error = new Error(
+        payload.message ?? `Notion API request failed with status ${response.status}`
+      );
+      error.status = response.status;
+      throw error;
+    }
+    return payload;
+  };
+}
+
+async function notionPageDocument(context, request, page) {
+  const id = requiredString(page.id, 'Notion page id');
+  const markdown = await request(
+    context,
+    'GET',
+    `/v1/pages/${encodeURIComponent(id)}/markdown`
+  );
+  let content = typeof markdown.markdown === 'string' ? markdown.markdown : '';
+  const unresolved = [];
+  for (const blockId of (markdown.unknown_block_ids ?? []).slice(0, 100)) {
+    try {
+      const block = await request(
+        context,
+        'GET',
+        `/v1/pages/${encodeURIComponent(blockId)}/markdown`
+      );
+      if (typeof block.markdown === 'string' && block.markdown.trim()) {
+        content += `\n\n${block.markdown}`;
+      }
+    } catch (error) {
+      if (error.status !== 404) throw error;
+      unresolved.push(blockId);
+    }
+  }
+  if (!content.trim()) content = `# ${notionTitle(page)}`;
+  return {
+    id,
+    title: notionTitle(page),
+    content,
+    url: onlineUrl(page.url),
+    updatedAt: dateTimeOrNull(page.last_edited_time),
+    metadata: {
+      notionObject: page.object ?? 'page',
+      parent: jsonObject(page.parent),
+      markdownTruncated: markdown.truncated === true,
+      unresolvedBlockIds: unresolved
+    }
+  };
+}
+
+function notionSources(source, { allowEmpty = false } = {}) {
+  const pageIds = idArray(source?.pageIds, 'Notion pageIds');
+  const dataSourceIds = idArray(source?.dataSourceIds, 'Notion dataSourceIds');
+  const sources = [
+    ...pageIds.map((id) => ({ kind: 'page', id })),
+    ...dataSourceIds.map((id) => ({ kind: 'data_source', id }))
+  ];
+  if (!allowEmpty && sources.length === 0) {
+    throw new TypeError('Notion source requires pageIds or dataSourceIds');
+  }
+  return sources;
+}
+
+function notionPageIsBound(page, sources) {
+  if (sources.some(({ kind, id }) => kind === 'page' && id === page.id)) return true;
+  const parentId = page.parent?.data_source_id ?? page.parent?.database_id;
+  return sources.some(({ kind, id }) => kind === 'data_source' && id === parentId);
+}
+
+function pageSummary(page) {
+  return {
+    id: page.id,
+    title: notionTitle(page),
+    type: 'page',
+    url: onlineUrl(page.url),
+    updatedAt: dateTimeOrNull(page.last_edited_time),
+    metadata: { parent: jsonObject(page.parent) }
+  };
+}
+
+function notionTitle(page) {
+  for (const property of Object.values(page.properties ?? {})) {
+    if (property?.type !== 'title' || !Array.isArray(property.title)) continue;
+    const title = property.title.map((item) => item?.plain_text ?? '').join('').trim();
+    if (title) return title;
+  }
+  return page.title?.map?.((item) => item?.plain_text ?? '').join('').trim()
+    || page.id
+    || 'Untitled Notion page';
+}
+
+function nextSourceCursor(index, length) {
+  return index + 1 < length
+    ? encodeCursor({ sourceIndex: index + 1, startCursor: null })
+    : null;
+}
+
+function encodeCursor(value) {
+  return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+
+function decodeCursor(value) {
+  if (!value) return { sourceIndex: 0, startCursor: null };
+  try {
+    const parsed = JSON.parse(Buffer.from(value, 'base64url').toString('utf8'));
+    if (!Number.isInteger(parsed.sourceIndex) || parsed.sourceIndex < 0) throw new Error();
+    if (parsed.startCursor !== null && typeof parsed.startCursor !== 'string') throw new Error();
+    return parsed;
+  } catch {
+    throw new TypeError('Invalid Notion synchronization cursor');
+  }
+}
+
+function emptySyncPage() {
+  return { items: [], deleted: [], nextCursor: null, hasMore: false };
+}
+
+function credentialFromEnvironment(context, key, label) {
+  const name = context.config?.[key];
+  if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(name)) {
+    throw new TypeError(`${label} environment variable name is required`);
+  }
+  const value = context.env?.[name];
+  if (typeof value !== 'string' || !value) {
+    throw new TypeError(`${label} environment variable is unavailable: ${name}`);
+  }
+  return value;
+}
+
+function idArray(value, label) {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== 'string' || !item.trim())) {
+    throw new TypeError(`${label} must be an array of nonempty strings`);
+  }
+  return [...new Set(value.map((item) => item.trim()))];
+}
+
+function pageSize(value) {
+  if (value === undefined || value === null) return 100;
+  if (!Number.isInteger(value) || value <= 0) throw new TypeError('Notion page size is invalid');
+  return Math.min(value, 100);
+}
+
+function timeoutMilliseconds(value) {
+  if (value === undefined || value === null) return 30_000;
+  if (!Number.isInteger(value) || value < 1_000 || value > 120_000) {
+    throw new TypeError('Notion timeoutMs must be between 1000 and 120000');
+  }
+  return value;
+}
+
+function requiredString(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
+  return value.trim();
+}
+
+function onlineUrl(value) {
+  if (typeof value !== 'string') return null;
+  try {
+    const url = new URL(value);
+    return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password
+      ? url.toString()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function dateTimeOrNull(value) {
+  if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) return null;
+  return new Date(value).toISOString();
+}
+
+function jsonObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? structuredClone(value)
+    : {};
+}

package/src/external-knowledge/connectors/retrieval-api.js

@@ -0,0 +1,222 @@
+import { createHash } from 'node:crypto';
+
+const DEFAULT_SCORE_THRESHOLD = 0.5;
+const MAX_KNOWLEDGE_BASES = 32;
+
+export function createRetrievalApiConnector({ fetchImpl = globalThis.fetch } = {}) {
+  if (typeof fetchImpl !== 'function') {
+    throw new TypeError('Retrieval API fetch is unavailable');
+  }
+
+  async function retrieve(context, { checking = false } = {}) {
+    const endpoint = retrievalEndpoint(context.config?.url);
+    const knowledgeIds = idArray(context.source?.knowledgeIds, 'knowledgeIds');
+    const limit = checking ? 1 : positiveInteger(context.limit ?? 12, 'limit', 100);
+    const query = checking
+      ? 'FULI connection check'
+      : requiredString(context.query, 'Retrieval query', 2_000);
+    const results = await Promise.all(knowledgeIds.map(async (knowledgeId) => {
+      const payload = await request(fetchImpl, endpoint, context, {
+        knowledge_id: knowledgeId,
+        query,
+        retrieval_setting: {
+          top_k: limit,
+          score_threshold: scoreThreshold(context.config?.scoreThreshold)
+        }
+      });
+      if (!Array.isArray(payload.records)) {
+        throw new TypeError('Retrieval API response records must be an array');
+      }
+      return payload.records.slice(0, limit).map((record, index) =>
+        retrievalDocument(record, { knowledgeId, index })
+      );
+    }));
+    return {
+      items: results.flat()
+        .sort((left, right) => (right.metadata.score ?? 0) - (left.metadata.score ?? 0))
+        .slice(0, limit)
+    };
+  }
+
+  return {
+    type: 'retrieval_api',
+    name: 'RAG Retrieval API',
+    capabilities: ['retrieve'],
+
+    async check(context) {
+      await retrieve(context, { checking: true });
+      return {
+        status: 'ready',
+        capabilities: ['retrieve'],
+        protocol: 'dify_external_knowledge_v1'
+      };
+    },
+
+    retrieve
+  };
+}
+
+async function request(fetchImpl, endpoint, context, body) {
+  const headers = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json'
+  };
+  const tokenName = optionalEnvironmentName(context.config?.tokenEnv, 'tokenEnv');
+  if (tokenName) {
+    const token = context.env?.[tokenName];
+    if (typeof token !== 'string' || !token) {
+      throw new TypeError(`Retrieval API token environment variable is unavailable: ${tokenName}`);
+    }
+    headers.Authorization = `Bearer ${token}`;
+  }
+  const response = await fetchImpl(endpoint, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMilliseconds(context.config?.timeoutMs))
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(
+      payload?.message ?? payload?.error ??
+      `Retrieval API request failed with status ${response.status}`
+    );
+  }
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new TypeError('Retrieval API response must be an object');
+  }
+  return payload;
+}
+
+function retrievalDocument(record, { knowledgeId, index }) {
+  if (!record || typeof record !== 'object' || Array.isArray(record)) {
+    throw new TypeError('Retrieval API records must be objects');
+  }
+  const metadata = jsonObject(record.metadata);
+  const content = requiredString(record.content, 'Retrieval record content', 1_000_000);
+  const title = firstString(
+    record.title,
+    metadata.title,
+    metadata.document_name,
+    metadata.filename,
+    `Knowledge result ${index + 1}`
+  );
+  const sourceId = firstString(
+    metadata.segment_id,
+    metadata.chunk_id,
+    metadata.document_id,
+    metadata.id,
+    metadata.path,
+    metadata.url,
+    metadata.source_url
+  ) ?? createHash('sha256')
+    .update(`${knowledgeId}\0${title}\0${content}`)
+    .digest('hex');
+  const combinedId = `${knowledgeId}:${sourceId}`;
+  return {
+    id: combinedId.length <= 512
+      ? combinedId
+      : `retrieval:${createHash('sha256').update(combinedId).digest('hex')}`,
+    title,
+    content,
+    url: onlineUrl(firstString(metadata.url, metadata.source_url)),
+    updatedAt: dateTime(firstString(metadata.updated_at, metadata.updatedAt)),
+    metadata: {
+      ...metadata,
+      knowledgeId,
+      score: finiteNumber(record.score)
+    }
+  };
+}
+
+function retrievalEndpoint(value) {
+  const raw = requiredString(value, 'Retrieval API URL', 2_048);
+  const url = new URL(raw);
+  const loopback = url.hostname === 'localhost' ||
+    url.hostname === '127.0.0.1' ||
+    url.hostname === '[::1]';
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) ||
+      url.username || url.password) {
+    throw new TypeError('Retrieval API URL must use HTTPS or loopback HTTP without credentials');
+  }
+  return url.toString();
+}
+
+function idArray(value, label) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > MAX_KNOWLEDGE_BASES) {
+    throw new TypeError(`${label} must contain 1 to ${MAX_KNOWLEDGE_BASES} IDs`);
+  }
+  const ids = value.map((item) => requiredString(item, `${label} item`, 512));
+  if (new Set(ids).size !== ids.length) throw new TypeError(`${label} must be unique`);
+  return ids;
+}
+
+function scoreThreshold(value) {
+  if (value === undefined || value === null || value === '') return DEFAULT_SCORE_THRESHOLD;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new TypeError('scoreThreshold must be a number from 0 to 1');
+  }
+  return value;
+}
+
+function timeoutMilliseconds(value) {
+  if (value === undefined || value === null) return 20_000;
+  return positiveInteger(value, 'timeoutMs', 120_000);
+}
+
+function optionalEnvironmentName(value, label) {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/u.test(value)) {
+    throw new TypeError(`${label} must be an environment variable name`);
+  }
+  return value;
+}
+
+function jsonObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? structuredClone(value)
+    : {};
+}
+
+function onlineUrl(value) {
+  if (!value) return null;
+  try {
+    const url = new URL(value);
+    return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password
+      ? url.toString()
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function dateTime(value) {
+  return value && !Number.isNaN(Date.parse(value))
+    ? new Date(value).toISOString()
+    : null;
+}
+
+function finiteNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+function requiredString(value, label, maximum) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
+  const normalized = value.trim();
+  if (normalized.length > maximum) throw new TypeError(`${label} is too long`);
+  return normalized;
+}
+
+function positiveInteger(value, label, maximum) {
+  if (!Number.isInteger(value) || value <= 0 || value > maximum) {
+    throw new TypeError(`${label} must be a positive integer no greater than ${maximum}`);
+  }
+  return value;
+}

package/src/external-knowledge/document-mapping.js

@@ -0,0 +1,151 @@
+import { createHash } from 'node:crypto';
+
+import { detectSensitiveContent } from '../security/sensitive-content.js';
+
+const MAX_CHUNK_LENGTH = 6_000;
+const MAX_EXCERPT_LENGTH = 2_048;
+
+export function normalizeExternalDocument(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('Connector items must be objects');
+  }
+  const id = requiredString(value.id, 'Connector item id', 512);
+  const title = requiredString(value.title ?? value.name ?? id, 'Connector item title', 512);
+  const content = requiredString(value.content, 'Connector item content', 1_000_000);
+  const url = optionalOnlineUrl(value.url);
+  const updatedAt = optionalDateTime(value.updatedAt, 'Connector item updatedAt');
+  const metadata = plainJsonObject(value.metadata ?? {}, 'Connector item metadata');
+  if (detectSensitiveContent(JSON.stringify({ title, content, metadata })).restricted) {
+    throw new TypeError('Connector item contains credentials and cannot be retrieved or stored');
+  }
+  return { id, title, content, url, updatedAt, metadata };
+}
+
+export function externalDocumentHash(document) {
+  return createHash('sha256').update(JSON.stringify({
+    title: document.title,
+    content: document.content,
+    url: document.url,
+    updatedAt: document.updatedAt,
+    metadata: document.metadata
+  })).digest('hex');
+}
+
+export function externalDocumentStateKey(id) {
+  return createHash('sha256').update(`external-document:${id}`).digest('hex');
+}
+
+export function externalDocumentEpisode({ binding, document, now }) {
+  const chunks = chunkText(document.content);
+  const itemDigest = shortHash(document.id);
+  const targetScopeId = binding.targetId ?? binding.id;
+  const referenceTime = document.updatedAt ?? now.toISOString();
+  return {
+    targetKind: 'personal',
+    spaceId: binding.target.personalSpaceId,
+    personalProjectId: binding.target.personalProjectId,
+    idempotencyKey: `external:${targetScopeId}:${itemDigest}:${externalDocumentHash(document)}`,
+    sessionId: `external:${targetScopeId}`,
+    name: document.title,
+    sourceKind: 'document',
+    sourceDescription: `Read-only ${binding.connectorType} knowledge source`,
+    sourceUri: document.url,
+    // The graph contract keeps source_application to a stable agent enum. The
+    // connector identity stays in sourceDescription and entity attributes.
+    sourceApplication: 'other',
+    sourceTurnId: document.id,
+    sourceExcerpt: document.content.slice(0, MAX_EXCERPT_LENGTH),
+    referenceTime,
+    summary: `Imported from the read-only binding “${binding.name}”.`,
+    sensitivity: 'restricted',
+    entities: chunks.map((content, index) => ({
+      key: `external:${targetScopeId}:${itemDigest}:${index + 1}`,
+      name: chunks.length === 1 ? document.title : `${document.title} (${index + 1}/${chunks.length})`,
+      type: 'ExternalKnowledgeDocument',
+      summary: content,
+      originQuadrant: 'known_known',
+      currentQuadrant: 'known_known',
+      epistemicStatus: 'observed',
+      confirmationStatus: 'pending',
+      confirmationBasis: {
+        existenceReason: 'A configured read-only connector returned this source document.',
+        quadrantReason: 'The source text is explicit, but FULI has not independently verified it.',
+        proposedBy: { kind: 'import', label: binding.connectorType }
+      },
+      inheritanceMode: 'local_only',
+      attributes: {
+        externalBindingId: binding.id,
+        externalBindingTargetId: targetScopeId,
+        externalConnectorType: binding.connectorType,
+        externalItemId: document.id,
+        externalItemUrl: document.url,
+        externalUpdatedAt: document.updatedAt,
+        externalChunk: index + 1,
+        externalChunkCount: chunks.length,
+        externalMetadata: document.metadata
+      }
+    })),
+    relationships: []
+  };
+}
+
+export function chunkText(content, maximum = MAX_CHUNK_LENGTH) {
+  if (content.length <= maximum) return [content];
+  const chunks = [];
+  let offset = 0;
+  while (offset < content.length) {
+    const end = Math.min(offset + maximum, content.length);
+    let split = end;
+    if (end < content.length) {
+      const candidate = Math.max(
+        content.lastIndexOf('\n\n', end),
+        content.lastIndexOf('\n', end),
+        content.lastIndexOf(' ', end)
+      );
+      if (candidate > offset + Math.floor(maximum / 2)) split = candidate;
+    }
+    chunks.push(content.slice(offset, split).trim());
+    offset = split;
+    while (/\s/u.test(content[offset] ?? '')) offset += 1;
+  }
+  return chunks.filter(Boolean);
+}
+
+function shortHash(value) {
+  return createHash('sha256').update(value).digest('hex').slice(0, 24);
+}
+
+function requiredString(value, label, maximum) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} is required`);
+  const normalized = value.trim();
+  if (normalized.length > maximum) throw new TypeError(`${label} is too long`);
+  return normalized;
+}
+
+function optionalOnlineUrl(value) {
+  if (value === undefined || value === null || value === '') return null;
+  const url = new URL(value);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) {
+    throw new TypeError('Connector item URL must be an HTTP(S) URL without credentials');
+  }
+  return url.toString();
+}
+
+function optionalDateTime(value, label) {
+  if (value === undefined || value === null || value === '') return null;
+  if (typeof value !== 'string' || Number.isNaN(Date.parse(value))) {
+    throw new TypeError(`${label} must be an ISO date-time`);
+  }
+  return new Date(value).toISOString();
+}
+
+function plainJsonObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError(`${label} must be an object`);
+  }
+  try {
+    return structuredClone(value);
+  } catch {
+    throw new TypeError(`${label} must contain JSON-compatible values`);
+  }
+}

package/src/external-knowledge/graph-projection.js

@@ -0,0 +1,17 @@
+export function mergeExternalKnowledgeProjection(
+  externalKnowledge,
+  graph,
+  personalSpaceId,
+  personalProjectId
+) {
+  const projection = externalKnowledge?.projectGraphProjection?.({
+    personalSpaceId,
+    personalProjectId,
+    graph
+  }) ?? { nodes: [], edges: [] };
+  return {
+    ...graph,
+    nodes: [...graph.nodes, ...projection.nodes],
+    edges: [...graph.edges, ...projection.edges]
+  };
+}