@pellux/goodvibes-sdk 0.28.22 → 0.30.1

package/dist/platform/knowledge/generated-pages.d.ts

@@ -0,0 +1,62 @@
+import type { ArtifactStore } from '../artifacts/index.js';
+import type { KnowledgeEdgeRecord, KnowledgeNodeRecord, KnowledgeSourceRecord } from './types.js';
+export interface GeneratedKnowledgePageGraphNode {
+    readonly id: string;
+    readonly kind: string;
+    readonly title: string;
+    readonly [key: string]: unknown;
+}
+export type GeneratedKnowledgePageGraphNeighbor<TNode extends GeneratedKnowledgePageGraphNode = GeneratedKnowledgePageGraphNode> = TNode & {
+    readonly relation: string;
+    readonly direction: 'incoming' | 'outgoing';
+};
+export interface GeneratedKnowledgeRelatedPage<TNode extends GeneratedKnowledgePageGraphNode = GeneratedKnowledgePageGraphNode> {
+    readonly sourceId: string;
+    readonly title: string;
+    readonly projectionKind?: string;
+    readonly subject?: TNode;
+}
+export interface GeneratedKnowledgePageEntry<TNode extends GeneratedKnowledgePageGraphNode = GeneratedKnowledgePageGraphNode> {
+    readonly source: KnowledgeSourceRecord;
+    readonly artifact?: {
+        readonly id: string;
+        readonly mimeType: string;
+        readonly filename?: string;
+        readonly createdAt: number;
+        readonly metadata: Record<string, unknown>;
+    };
+    readonly markdown?: string;
+    readonly target?: TNode;
+    readonly subject?: TNode;
+    readonly neighbors?: readonly GeneratedKnowledgePageGraphNeighbor<TNode>[];
+    readonly relatedPages?: readonly GeneratedKnowledgeRelatedPage<TNode>[];
+}
+export interface GeneratedKnowledgePageListResult<TNode extends GeneratedKnowledgePageGraphNode = GeneratedKnowledgePageGraphNode> {
+    readonly ok: true;
+    readonly spaceId: string;
+    readonly pages: readonly GeneratedKnowledgePageEntry<TNode>[];
+}
+export interface GeneratedKnowledgePageListOptions<TNode extends GeneratedKnowledgePageGraphNode = GeneratedKnowledgePageGraphNode> {
+    readonly artifactStore: ArtifactStore;
+    readonly spaceId: string;
+    readonly sources: readonly KnowledgeSourceRecord[];
+    readonly nodes: readonly KnowledgeNodeRecord[];
+    readonly edges: readonly KnowledgeEdgeRecord[];
+    readonly limit: number;
+    readonly includeMarkdown: boolean;
+    readonly isGeneratedSource?: (source: KnowledgeSourceRecord) => boolean;
+    readonly isPageSubjectNode?: (node: KnowledgeNodeRecord) => boolean;
+    readonly resolvePageSubject?: (target: KnowledgeNodeRecord, graph: GeneratedKnowledgePageGraph) => KnowledgeNodeRecord | undefined;
+    readonly projectNode?: (node: KnowledgeNodeRecord) => TNode;
+    readonly compareGeneratedPages?: (left: KnowledgeSourceRecord, right: KnowledgeSourceRecord, graph: GeneratedKnowledgePageGraph) => number;
+    readonly relatedPageLimit?: number;
+}
+export interface GeneratedKnowledgePageGraph {
+    readonly nodesById: ReadonlyMap<string, KnowledgeNodeRecord>;
+    readonly edges: readonly KnowledgeEdgeRecord[];
+    readonly generatedSources: readonly KnowledgeSourceRecord[];
+    readonly targetBySourceId: ReadonlyMap<string, KnowledgeNodeRecord>;
+}
+export declare function listGeneratedKnowledgePages<TNode extends GeneratedKnowledgePageGraphNode = GeneratedKnowledgePageGraphNode>(input: GeneratedKnowledgePageListOptions<TNode>): Promise<GeneratedKnowledgePageListResult<TNode>>;
+export declare function buildGeneratedKnowledgePageGraph(sources: readonly KnowledgeSourceRecord[], nodes: readonly KnowledgeNodeRecord[], edges: readonly KnowledgeEdgeRecord[], isGeneratedSource?: (source: KnowledgeSourceRecord) => boolean): GeneratedKnowledgePageGraph;
+//# sourceMappingURL=generated-pages.d.ts.map

package/dist/platform/knowledge/generated-pages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-pages.d.ts","sourceRoot":"","sources":["../../../src/platform/knowledge/generated-pages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAI3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAKlG,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACjC;AAED,MAAM,MAAM,mCAAmC,CAAC,KAAK,SAAS,+BAA+B,GAAG,+BAA+B,IAC7H,KAAK,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAAA;CAAE,CAAC;AAErF,MAAM,WAAW,6BAA6B,CAAC,KAAK,SAAS,+BAA+B,GAAG,+BAA+B;IAC5H,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,2BAA2B,CAAC,KAAK,SAAS,+BAA+B,GAAG,+BAA+B;IAC1H,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC5C,CAAC;IACF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,mCAAmC,CAAC,KAAK,CAAC,EAAE,CAAC;IAC3E,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,6BAA6B,CAAC,KAAK,CAAC,EAAE,CAAC;CACzE;AAED,MAAM,WAAW,gCAAgC,CAAC,KAAK,SAAS,+BAA+B,GAAG,+BAA+B;IAC/H,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,2BAA2B,CAAC,KAAK,CAAC,EAAE,CAAC;CAC/D;AAED,MAAM,WAAW,iCAAiC,CAAC,KAAK,SAAS,+BAA+B,GAAG,+BAA+B;IAChI,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,OAAO,CAAC;IACxE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,OAAO,CAAC;IACpE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,mBAAmB,EAAE,KAAK,EAAE,2BAA2B,KAAK,mBAAmB,GAAG,SAAS,CAAC;IACnI,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,KAAK,CAAC;IAC5D,QAAQ,CAAC,qBAAqB,CAAC,EAAE,CAC/B,IAAI,EAAE,qBAAqB,EAC3B,KAAK,EAAE,qBAAqB,EAC5B,KAAK,EAAE,2BAA2B,KAC/B,MAAM,CAAC;IACZ,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC5D,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CACrE;AAED,wBAAsB,2BAA2B,CAAC,KAAK,SAAS,+BAA+B,GAAG,+BAA+B,EAC/H,KAAK,EAAE,iCAAiC,CAAC,KAAK,CAAC,GAC9C,OAAO,CAAC,gCAAgC,CAAC,KAAK,CAAC,CAAC,CAoClD;AAED,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,SAAS,qBAAqB,EAAE,EACzC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,KAAK,EAAE,SAAS,mBAAmB,EAAE,EACrC,iBAAiB,GAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,OAAoC,GACzF,2BAA2B,CAe7B"}

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

@@ -0,0 +1,163 @@
+import { logger } from '../utils/logger.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
+import { isGeneratedKnowledgeSource } from './generated-projections.js';
+const DEFAULT_RELATED_GENERATED_PAGES = 24;
+const GENERATED_PAGE_MARKDOWN_READ_CONCURRENCY = 8;
+export async function listGeneratedKnowledgePages(input) {
+    const graph = buildGeneratedKnowledgePageGraph(input.sources, input.nodes, input.edges, input.isGeneratedSource);
+    const projectNode = input.projectNode ?? defaultPageGraphNode;
+    const resolveSubject = input.resolvePageSubject ?? defaultResolvePageSubject;
+    const isSubject = input.isPageSubjectNode ?? defaultIsPageSubjectNode;
+    const relatedPageLimit = input.relatedPageLimit ?? DEFAULT_RELATED_GENERATED_PAGES;
+    const sources = input.sources
+        .filter(input.isGeneratedSource ?? isGeneratedKnowledgeSource)
+        .sort((left, right) => input.compareGeneratedPages?.(left, right, graph) ?? compareGeneratedPages(left, right, graph))
+        .slice(0, input.limit);
+    const pages = await mapWithConcurrency(sources, GENERATED_PAGE_MARKDOWN_READ_CONCURRENCY, async (source) => {
+        const artifact = typeof source.artifactId === 'string' ? input.artifactStore.get(source.artifactId) : undefined;
+        const markdown = input.includeMarkdown && artifact
+            ? await readMarkdown(input.artifactStore, artifact.id)
+            : undefined;
+        const target = graph.targetBySourceId.get(source.id);
+        const subject = target ? resolveSubject(target, graph) : undefined;
+        return {
+            source,
+            ...(artifact ? {
+                artifact: {
+                    id: artifact.id,
+                    mimeType: artifact.mimeType,
+                    filename: artifact.filename,
+                    createdAt: artifact.createdAt,
+                    metadata: artifact.metadata,
+                },
+            } : {}),
+            ...(markdown ? { markdown } : {}),
+            ...(target ? { target: projectNode(target) } : {}),
+            ...(subject ? { subject: projectNode(subject) } : {}),
+            ...(subject ? { neighbors: pageNeighbors(subject, graph, isSubject, projectNode) } : {}),
+            ...(subject ? { relatedPages: relatedPages(source.id, subject, graph, resolveSubject, isSubject, projectNode, relatedPageLimit) } : {}),
+        };
+    });
+    return { ok: true, spaceId: input.spaceId, pages };
+}
+export function buildGeneratedKnowledgePageGraph(sources, nodes, edges, isGeneratedSource = isGeneratedKnowledgeSource) {
+    const nodesById = new Map(nodes.map((node) => [node.id, node]));
+    const activeEdges = edges.filter(edgeIsActive);
+    const targetBySourceId = new Map();
+    for (const source of sources.filter(isGeneratedSource)) {
+        const targetEdge = activeEdges.find((edge) => edge.fromKind === 'source' && edge.fromId === source.id && edge.toKind === 'node');
+        const target = targetEdge ? nodesById.get(targetEdge.toId) : undefined;
+        if (target)
+            targetBySourceId.set(source.id, target);
+    }
+    return {
+        nodesById,
+        edges: activeEdges,
+        generatedSources: sources.filter(isGeneratedSource),
+        targetBySourceId,
+    };
+}
+function defaultResolvePageSubject(target, graph) {
+    if (defaultIsPageSubjectNode(target))
+        return target;
+    const related = graph.edges.find((edge) => (edge.fromKind === 'node'
+        && edge.fromId === target.id
+        && edge.toKind === 'node'
+        && edge.relation === 'source_for'));
+    return related ? graph.nodesById.get(related.toId) : undefined;
+}
+function relatedPages(currentSourceId, subject, graph, resolveSubject, isSubject, projectNode, limit) {
+    const neighborIds = new Set(pageNeighbors(subject, graph, isSubject, projectNode).map((neighbor) => neighbor.id));
+    neighborIds.add(subject.id);
+    const result = [];
+    for (const source of graph.generatedSources) {
+        if (source.id === currentSourceId)
+            continue;
+        const target = graph.targetBySourceId.get(source.id);
+        if (!target)
+            continue;
+        const pageSubject = resolveSubject(target, graph);
+        if (!pageSubject || !neighborIds.has(pageSubject.id))
+            continue;
+        result.push({
+            sourceId: source.id,
+            title: source.title ?? source.id,
+            ...(typeof source.metadata.projectionKind === 'string' ? { projectionKind: source.metadata.projectionKind } : {}),
+            subject: projectNode(pageSubject),
+        });
+    }
+    return result.slice(0, limit);
+}
+function pageNeighbors(subject, graph, isSubject, projectNode) {
+    const neighbors = [];
+    const seen = new Set();
+    for (const edge of graph.edges) {
+        if (edge.fromKind === 'node' && edge.fromId === subject.id && edge.toKind === 'node') {
+            const node = graph.nodesById.get(edge.toId);
+            if (node && isSubject(node))
+                pushNeighbor(neighbors, seen, projectNode(node), edge.relation, 'outgoing');
+        }
+        else if (edge.toKind === 'node' && edge.toId === subject.id && edge.fromKind === 'node') {
+            const node = graph.nodesById.get(edge.fromId);
+            if (node && isSubject(node))
+                pushNeighbor(neighbors, seen, projectNode(node), edge.relation, 'incoming');
+        }
+    }
+    return neighbors.slice(0, 48);
+}
+function pushNeighbor(neighbors, seen, node, relation, direction) {
+    const key = `${node.id}:${relation}:${direction}`;
+    if (seen.has(key))
+        return;
+    seen.add(key);
+    neighbors.push({ ...node, relation, direction });
+}
+function defaultIsPageSubjectNode(node) {
+    if (node.status === 'stale')
+        return false;
+    if (node.metadata.semanticKind)
+        return false;
+    return !['fact', 'knowledge_gap', 'wiki_page'].includes(node.kind);
+}
+function defaultPageGraphNode(node) {
+    return {
+        id: node.id,
+        kind: node.kind,
+        title: node.title,
+    };
+}
+function compareGeneratedPages(left, right, graph) {
+    const leftKind = typeof left.metadata.projectionKind === 'string' ? left.metadata.projectionKind : '';
+    const rightKind = typeof right.metadata.projectionKind === 'string' ? right.metadata.projectionKind : '';
+    return generatedPagePriority(right, graph) - generatedPagePriority(left, graph)
+        || leftKind.localeCompare(rightKind)
+        || (left.title ?? left.id).localeCompare(right.title ?? right.id)
+        || left.id.localeCompare(right.id);
+}
+function generatedPagePriority(source, graph) {
+    const target = graph.targetBySourceId.get(source.id);
+    const subject = target ? defaultResolvePageSubject(target, graph) : undefined;
+    const projectionKind = typeof source.metadata.projectionKind === 'string' ? source.metadata.projectionKind : '';
+    let score = 0;
+    if (projectionKind)
+        score += 10;
+    if (subject)
+        score += 10;
+    return score;
+}
+async function readMarkdown(artifactStore, artifactId) {
+    try {
+        const { buffer } = await artifactStore.readContent(artifactId);
+        return buffer.toString('utf-8');
+    }
+    catch (error) {
+        logger.debug('Generated knowledge page markdown read failed', {
+            artifactId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+function edgeIsActive(edge) {
+    return edge.weight > 0 && edge.metadata.deleted !== true;
+}

package/dist/platform/knowledge/generated-projections.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-projections.d.ts","sourceRoot":"","sources":["../../../src/platform/knowledge/generated-projections.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACtB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,mBAAmB,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;QACtC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CACnC;AAED,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAElF;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAKjF;AAED,wBAAsB,uCAAuC,CAC3D,KAAK,EAAE,iCAAiC,GACvC,OAAO,CAAC,kCAAkC,CAAC,CA0E7C"}

package/dist/platform/knowledge/generated-projections.js

@@ -0,0 +1,128 @@
+import { createHash } from 'node:crypto';
+import { logger } from '../utils/logger.js';
+export function generatedKnowledgeSourceId(kind, value) {
+    return `kg-gen-${stableHash(`${kind}:${value}`)}`;
+}
+export function generatedKnowledgeCanonicalUri(kind, value) {
+    return `knowledge://generated/${encodeURIComponent(kind)}/${stableHash(value, 20)}`;
+}
+export function isGeneratedKnowledgeSource(source) {
+    return source.metadata.generatedKnowledgePage === true
+        || source.metadata.generatedProjection === true
+        || source.metadata.homeGraphGeneratedPage === true
+        || source.metadata.homeGraphSourceKind === 'generated-page';
+}
+export async function materializeGeneratedKnowledgeProjection(input) {
+    const existing = input.store.getSource(input.sourceId);
+    const contentHash = stableHash(input.markdown, 40);
+    const existingMetadata = readRecord(existing?.metadata);
+    const existingGeneratedAt = typeof existingMetadata.generatedAt === 'number' ? existingMetadata.generatedAt : undefined;
+    const contentUnchanged = existingMetadata.generatedContentHash === contentHash;
+    const generatedAt = contentUnchanged && existingGeneratedAt !== undefined ? existingGeneratedAt : Date.now();
+    const projectionMetadata = {
+        ...(input.metadata ?? {}),
+        generatedKnowledgePage: true,
+        generatedProjection: true,
+        projectionKind: input.projectionKind,
+        generatedAt,
+        generatedContentHash: contentHash,
+        pageEditable: true,
+    };
+    const reusedArtifact = await findReusableGeneratedArtifact(input.artifactStore, existing, input.markdown);
+    const artifact = reusedArtifact ?? await input.artifactStore.create({
+        kind: 'document',
+        mimeType: 'text/markdown',
+        filename: input.filename,
+        text: input.markdown,
+        retentionMs: 0,
+        metadata: {
+            ...projectionMetadata,
+            ...(input.artifactMetadata ?? {}),
+            generatedAt,
+            generatedContentHash: contentHash,
+        },
+    });
+    const source = await input.store.upsertSource({
+        id: input.sourceId,
+        connectorId: input.connectorId,
+        sourceType: input.sourceType ?? 'document',
+        title: input.title,
+        sourceUri: input.canonicalUri,
+        canonicalUri: input.canonicalUri,
+        ...(input.summary ? { summary: input.summary } : {}),
+        tags: uniqueStrings(input.tags ?? []),
+        status: 'indexed',
+        artifactId: artifact.id,
+        lastCrawledAt: contentUnchanged && typeof existing?.lastCrawledAt === 'number'
+            ? existing.lastCrawledAt
+            : generatedAt,
+        metadata: {
+            ...projectionMetadata,
+            artifactId: artifact.id,
+            filename: artifact.filename,
+            ...(input.sourceMetadata ?? {}),
+            generatedAt,
+            generatedContentHash: contentHash,
+        },
+    });
+    const linked = input.target
+        ? await input.store.upsertEdge({
+            fromKind: 'source',
+            fromId: source.id,
+            toKind: input.target.kind,
+            toId: input.target.id,
+            relation: input.target.relation ?? 'source_for',
+            metadata: {
+                generatedKnowledgePage: true,
+                generatedProjection: true,
+                projectionKind: input.projectionKind,
+                ...(input.edgeMetadata ?? {}),
+            },
+        })
+        : undefined;
+    return {
+        artifact,
+        source,
+        ...(linked ? { linked } : {}),
+        artifactCreated: !reusedArtifact,
+    };
+}
+async function findReusableGeneratedArtifact(artifactStore, source, markdown) {
+    if (!source?.artifactId)
+        return undefined;
+    const artifact = artifactStore.get(source.artifactId);
+    if (!artifact)
+        return undefined;
+    try {
+        const { buffer } = await artifactStore.readContent(artifact.id);
+        return buffer.toString('utf-8') === markdown ? artifact : undefined;
+    }
+    catch (error) {
+        logger.debug('Generated knowledge projection artifact reuse failed', {
+            sourceId: source.id,
+            artifactId: artifact.id,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+function stableHash(value, length = 24) {
+    return createHash('sha256').update(value).digest('hex').slice(0, length);
+}
+function readRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function uniqueStrings(values) {
+    const seen = new Set();
+    const result = [];
+    for (const value of values) {
+        const trimmed = typeof value === 'string' ? value.trim() : '';
+        if (!trimmed || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        result.push(trimmed);
+    }
+    return result;
+}

package/dist/platform/knowledge/graphql-schema.d.ts

@@ -1,2 +1,45 @@
-export * from '../../_internal/platform/knowledge/graphql-schema.js';
+import { buildSchema, type DocumentNode, type ValueNode } from 'graphql';
+import type { KnowledgePacketDetail, KnowledgeProjectionTargetKind } from './types.js';
+export declare const KNOWLEDGE_GRAPHQL_SDL = "\n  scalar JSON\n\n  enum KnowledgeProjectionKind {\n    OVERVIEW\n    BUNDLE\n    SOURCE\n    NODE\n    ISSUE\n    DASHBOARD\n    ROLLUP\n  }\n\n  enum KnowledgePacketDetail {\n    COMPACT\n    STANDARD\n    DETAILED\n  }\n\n  enum KnowledgeJobMode {\n    INLINE\n    BACKGROUND\n  }\n\n  type KnowledgeStatus {\n    ready: Boolean!\n    storagePath: String!\n    sourceCount: Int!\n    nodeCount: Int!\n    edgeCount: Int!\n    issueCount: Int!\n    extractionCount: Int!\n    jobRunCount: Int!\n    usageCount: Int!\n    candidateCount: Int!\n    reportCount: Int!\n    scheduleCount: Int!\n    note: String!\n  }\n\n  type KnowledgeConnectorSetupField {\n    key: String!\n    label: String!\n    kind: String!\n    optional: Boolean\n    source: String\n    description: String\n  }\n\n  type KnowledgeConnectorSetup {\n    version: String!\n    summary: String!\n    transportHints: [String!]!\n    steps: [String!]!\n    fields: [KnowledgeConnectorSetupField!]!\n    metadata: JSON\n  }\n\n  type KnowledgeConnectorDoctorCheck {\n    id: String!\n    label: String!\n    status: String!\n    detail: String!\n    metadata: JSON\n  }\n\n  type KnowledgeConnectorDoctorReport {\n    connectorId: String!\n    ready: Boolean!\n    summary: String!\n    checks: [KnowledgeConnectorDoctorCheck!]!\n    hints: [String!]!\n    metadata: JSON\n  }\n\n  type KnowledgeConnector {\n    id: String!\n    displayName: String\n    version: String\n    description: String!\n    sourceType: String!\n    inputSchema: JSON\n    examples: [JSON!]!\n    capabilities: [String!]!\n    setup: KnowledgeConnectorSetup\n    metadata: JSON\n  }\n\n  type KnowledgeSource {\n    id: String!\n    connectorId: String!\n    sourceType: String!\n    title: String\n    sourceUri: String\n    canonicalUri: String\n    summary: String\n    description: String\n    tags: [String!]!\n    folderPath: String\n    status: String!\n    artifactId: String\n    contentHash: String\n    lastCrawledAt: Float\n    crawlError: String\n    sessionId: String\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  type KnowledgeNode {\n    id: String!\n    kind: String!\n    slug: String!\n    title: String!\n    summary: String\n    aliases: [String!]!\n    status: String!\n    confidence: Int!\n    sourceId: String\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  type KnowledgeEdge {\n    id: String!\n    fromKind: String!\n    fromId: String!\n    toKind: String!\n    toId: String!\n    relation: String!\n    weight: Float!\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  type KnowledgeIssue {\n    id: String!\n    severity: String!\n    code: String!\n    message: String!\n    status: String!\n    sourceId: String\n    nodeId: String\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  type KnowledgeExtraction {\n    id: String!\n    sourceId: String!\n    artifactId: String\n    extractorId: String!\n    format: String!\n    title: String\n    summary: String\n    excerpt: String\n    sections: [String!]!\n    links: [String!]!\n    estimatedTokens: Int!\n    structure: JSON\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  type KnowledgeItemView {\n    source: KnowledgeSource\n    node: KnowledgeNode\n    issue: KnowledgeIssue\n    relatedEdges: [KnowledgeEdge!]!\n    linkedSources: [KnowledgeSource!]!\n    linkedNodes: [KnowledgeNode!]!\n  }\n\n  type KnowledgeSearchResult {\n    kind: String!\n    id: String!\n    score: Float!\n    reason: String!\n    source: KnowledgeSource\n    node: KnowledgeNode\n  }\n\n  type KnowledgePacketItem {\n    kind: String!\n    id: String!\n    title: String!\n    summary: String\n    uri: String\n    reason: String!\n    score: Float!\n    estimatedTokens: Int!\n    related: [String!]!\n    evidence: [String!]!\n    metadata: JSON\n  }\n\n  type KnowledgePacket {\n    task: String!\n    writeScope: [String!]!\n    generatedAt: Float!\n    detail: KnowledgePacketDetail!\n    strategy: String!\n    budgetLimit: Int!\n    estimatedTokens: Int!\n    items: [KnowledgePacketItem!]!\n  }\n\n  type KnowledgeProjectionTarget {\n    targetId: String!\n    kind: KnowledgeProjectionKind!\n    title: String!\n    description: String!\n    itemId: String\n    defaultPath: String!\n    defaultFilename: String!\n    metadata: JSON\n  }\n\n  type KnowledgeProjectionPage {\n    path: String!\n    title: String!\n    format: String!\n    content: String!\n    itemIds: [String!]!\n    metadata: JSON\n  }\n\n  type KnowledgeProjectionBundle {\n    id: String!\n    target: KnowledgeProjectionTarget!\n    generatedAt: Float!\n    pageCount: Int!\n    pages: [KnowledgeProjectionPage!]!\n    metadata: JSON\n  }\n\n  type ArtifactDescriptor {\n    id: String!\n    kind: String!\n    mimeType: String!\n    filename: String\n    sizeBytes: Int!\n    sourceUri: String\n    createdAt: Float!\n    metadata: JSON\n  }\n\n  type KnowledgeJob {\n    id: String!\n    label: String!\n    description: String!\n    defaultMode: KnowledgeJobMode!\n    triggerKinds: [String!]!\n    lastRunAt: Float\n    metadata: JSON\n  }\n\n  type KnowledgeJobRun {\n    id: String!\n    jobId: String!\n    status: String!\n    mode: KnowledgeJobMode!\n    requestedAt: Float!\n    startedAt: Float\n    completedAt: Float\n    error: String\n    result: JSON\n    metadata: JSON\n  }\n\n  type KnowledgeBatchIngestResult {\n    imported: Int!\n    failed: Int!\n    sources: [KnowledgeSource!]!\n    errors: [String!]!\n  }\n\n  type KnowledgeUsageRecord {\n    id: String!\n    targetKind: String!\n    targetId: String!\n    usageKind: String!\n    task: String\n    sessionId: String\n    score: Float\n    metadata: JSON\n    createdAt: Float!\n  }\n\n  type KnowledgeConsolidationCandidate {\n    id: String!\n    candidateType: String!\n    status: String!\n    subjectKind: String!\n    subjectId: String!\n    title: String!\n    summary: String\n    score: Float!\n    evidence: [String!]!\n    suggestedMemoryClass: String\n    suggestedScope: String\n    decidedAt: Float\n    decidedBy: String\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  type KnowledgeConsolidationReport {\n    id: String!\n    kind: String!\n    title: String!\n    summary: String!\n    highlights: [String!]!\n    metrics: JSON\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  type KnowledgeSchedule {\n    id: String!\n    jobId: String!\n    label: String!\n    enabled: Boolean!\n    schedule: JSON!\n    lastRunAt: Float\n    nextRunAt: Float\n    metadata: JSON\n    createdAt: Float!\n    updatedAt: Float!\n  }\n\n  input KnowledgeJobRunInput {\n    mode: KnowledgeJobMode\n  }\n\n  input KnowledgePacketInput {\n    task: String!\n    writeScope: [String!]\n    limit: Int\n    detail: KnowledgePacketDetail\n    budgetLimit: Int\n  }\n\n  type Query {\n    status: KnowledgeStatus!\n    connectors: [KnowledgeConnector!]!\n    connectorDoctor(id: String!): KnowledgeConnectorDoctorReport\n    sources(limit: Int, offset: Int, knowledgeSpaceId: String): [KnowledgeSource!]!\n    nodes(limit: Int, offset: Int, knowledgeSpaceId: String): [KnowledgeNode!]!\n    issues(limit: Int, offset: Int, knowledgeSpaceId: String): [KnowledgeIssue!]!\n    itemView(kind: String!, id: String!): KnowledgeItemView\n    extractions(limit: Int, sourceId: String, knowledgeSpaceId: String): [KnowledgeExtraction!]!\n    neighbors(kind: String!, id: String!, relation: String, limit: Int): [KnowledgeEdge!]!\n    search(query: String!, limit: Int, knowledgeSpaceId: String): [KnowledgeSearchResult!]!\n    packet(task: String!, writeScope: [String!], limit: Int, detail: KnowledgePacketDetail, budgetLimit: Int): KnowledgePacket!\n    projectionTargets(limit: Int): [KnowledgeProjectionTarget!]!\n    projection(kind: KnowledgeProjectionKind!, id: String, limit: Int): KnowledgeProjectionBundle!\n    jobs: [KnowledgeJob!]!\n    job(id: String!): KnowledgeJob\n    jobRuns(limit: Int, jobId: String): [KnowledgeJobRun!]!\n    usage(limit: Int, targetKind: String, targetId: String, usageKind: String): [KnowledgeUsageRecord!]!\n    usageRecords(limit: Int, targetKind: String, targetId: String, usageKind: String): [KnowledgeUsageRecord!]!\n    consolidationCandidates(limit: Int, status: String): [KnowledgeConsolidationCandidate!]!\n    consolidationReports(limit: Int): [KnowledgeConsolidationReport!]!\n    schedules(limit: Int): [KnowledgeSchedule!]!\n    sourceExtraction(sourceId: String!): KnowledgeExtraction\n  }\n\n  type Mutation {\n    ingestUrl(url: String!, sourceType: String, connectorId: String, folderPath: String, tags: [String!], sessionId: String, allowPrivateHosts: Boolean): KnowledgeSource!\n    ingestArtifact(path: String!, connectorId: String, tags: [String!], sessionId: String, allowPrivateHosts: Boolean): KnowledgeSource!\n    importBookmarksFromFile(path: String!, sessionId: String, allowPrivateHosts: Boolean): KnowledgeBatchIngestResult!\n    importUrlsFromFile(path: String!, sessionId: String, allowPrivateHosts: Boolean): KnowledgeBatchIngestResult!\n    ingestBookmarkSeeds(seeds: [String!]!, connectorId: String, sessionId: String): KnowledgeBatchIngestResult!\n    ingestWithConnector(connectorId: String!, input: String!, sessionId: String, allowPrivateHosts: Boolean): KnowledgeBatchIngestResult!\n    ingestConnectorInput(input: String!, connectorId: String, sessionId: String, allowPrivateHosts: Boolean): KnowledgeBatchIngestResult!\n    renderProjection(kind: KnowledgeProjectionKind!, id: String, limit: Int): KnowledgeProjectionBundle!\n    materializeProjection(kind: KnowledgeProjectionKind!, id: String, limit: Int): KnowledgeMaterializedProjection!\n    reindex: KnowledgeStatus!\n    runJob(id: String!, mode: KnowledgeJobMode): KnowledgeJobRun!\n    saveSchedule(id: String, jobId: String!, label: String!, enabled: Boolean!, schedule: JSON!, metadata: JSON): KnowledgeSchedule!\n    deleteSchedule(id: String!): Boolean!\n    setScheduleEnabled(id: String!, enabled: Boolean!): KnowledgeSchedule\n    decideConsolidationCandidate(id: String!, status: String!, decidedBy: String): KnowledgeConsolidationCandidate!\n    lint: [KnowledgeIssue!]!\n  }\n\n  type KnowledgeMaterializedProjection {\n    artifact: ArtifactDescriptor!\n    bundle: KnowledgeProjectionBundle!\n  }\n";
+export declare function parseJsonAst(node: ValueNode): unknown;
+export declare function installJsonScalar(schema: ReturnType<typeof buildSchema>): void;
+export declare function toProjectionKind(value: string): KnowledgeProjectionTargetKind;
+export declare function toProjectionEnum(value: string | undefined): string;
+export declare function toPacketDetail(value: string | undefined): KnowledgePacketDetail;
+export declare function toPacketDetailEnum(value: string | undefined): string;
+export declare function toJobMode(value: string | undefined): 'inline' | 'background';
+export declare function toJobModeEnum(value: string | undefined): string;
+export declare function mapProjectionTarget<T extends {
+    kind?: string;
+}>(target: T): T & {
+    kind: string;
+};
+export declare function mapProjectionBundle<T extends {
+    target: {
+        kind?: string;
+    };
+    pages: readonly unknown[];
+}>(bundle: T): T & {
+    target: {
+        kind: string;
+    };
+};
+export declare function mapPacket<T extends {
+    detail?: string;
+}>(packet: T): T & {
+    detail: string;
+};
+export declare function mapJob<T extends {
+    defaultMode?: string;
+}>(job: T): T & {
+    defaultMode: string;
+};
+export declare function mapJobRun<T extends {
+    mode?: string;
+}>(run: T): T & {
+    mode: string;
+};
+export declare function clampInt(value: number | null | undefined, fallback: number): number;
+export declare function clampOffset(value: number | null | undefined): number;
+export declare function pickOperation(document: DocumentNode, operationName?: string): 'query' | 'mutation';
 //# sourceMappingURL=graphql-schema.d.ts.map

package/dist/platform/knowledge/graphql-schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graphql-schema.d.ts","sourceRoot":"","sources":["../../../src/platform/knowledge/graphql-schema.ts"],"names":[],"mappings":"AAAA,cAAc,sDAAsD,CAAC"}
+{"version":3,"file":"graphql-schema.d.ts","sourceRoot":"","sources":["../../../src/platform/knowledge/graphql-schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAEvF,eAAO,MAAM,qBAAqB,wqUA8YjC,CAAC;AAEF,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAoBrD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,UAAU,CAAC,OAAO,WAAW,CAAC,GAAG,IAAI,CAQ9E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,6BAA6B,CAuB7E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAiBlE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,qBAAqB,CAM/E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAEpE;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,YAAY,CAE5E;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAE/D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAKhG;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAKnJ;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAK1F;AAED,wBAAgB,MAAM,CAAC,CAAC,SAAS;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,WAAW,EAAE,MAAM,CAAA;CAAE,CAK9F;AAED,wBAAgB,SAAS,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAKnF;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEnF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAEpE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,UAAU,CASlG"}