@roarpeng/graphflow 1.9.4 → 1.9.12

package/dist/graph/document-convert.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * document-convert.ts — Office/PDF → Markdown via @firecrawl/anydoc (optional).
+ *
+ * Survey (2026): Firecrawl anydoc leads format coverage/speed for Node;
+ * Microsoft MarkItDown is Python/LLM-oriented; Pandoc needs system install.
+ * GraphFlow prefers local-first Node: optionalDependency on @firecrawl/anydoc.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DOCUMENT_MAX_FILE_SIZE = exports.OFFICE_DOCUMENT_EXTENSIONS = void 0;
+exports.isOfficeDocumentPath = isOfficeDocumentPath;
+exports.resetDocumentConverterCache = resetDocumentConverterCache;
+exports.setDocumentConverterForTests = setDocumentConverterForTests;
+exports.convertDocumentToMarkdown = convertDocumentToMarkdown;
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+const node_path_2 = require("node:path");
+const logger_js_1 = require("../utils/logger.js");
+const ensure_anydoc_js_1 = require("../integrations/ensure-anydoc.js");
+const requireFn = (0, node_module_1.createRequire)(__filename);
+/** Extensions converted to Markdown before graph indexing. */
+exports.OFFICE_DOCUMENT_EXTENSIONS = [
+    ".pdf",
+    ".doc",
+    ".docx",
+    ".docm",
+    ".ppt",
+    ".pptx",
+    ".pptm",
+    ".xls",
+    ".xlsx",
+    ".xlsm",
+    ".odt",
+    ".ods",
+    ".odp",
+    ".rtf",
+    ".epub",
+    ".csv",
+];
+/** Larger than source files — PDFs/DOCX often exceed 200KB. */
+exports.DEFAULT_DOCUMENT_MAX_FILE_SIZE = 5_000_000;
+function isOfficeDocumentPath(filePath) {
+    const ext = (0, node_path_2.extname)(filePath).toLowerCase();
+    return exports.OFFICE_DOCUMENT_EXTENSIONS.includes(ext);
+}
+let anydocLoadAttempted = false;
+let anydocModule = null;
+function loadAnydoc() {
+    if (anydocLoadAttempted) {
+        return anydocModule;
+    }
+    anydocLoadAttempted = true;
+    try {
+        (0, ensure_anydoc_js_1.applyAnydocRequireEnv)((0, ensure_anydoc_js_1.resolveAnydocNodeModules)());
+        const loaded = (0, ensure_anydoc_js_1.tryRequireAnydoc)();
+        if (loaded) {
+            anydocModule = loaded;
+            return anydocModule;
+        }
+        anydocModule = requireFn("@firecrawl/anydoc");
+    }
+    catch (error) {
+        const fromEnv = process.env.GRAPHFLOW_ANYDOC_NODE_MODULES?.trim();
+        if (fromEnv) {
+            try {
+                const req = (0, node_module_1.createRequire)((0, node_path_1.join)(fromEnv, "@firecrawl", "anydoc", "package.json"));
+                anydocModule = req("@firecrawl/anydoc");
+                return anydocModule;
+            }
+            catch {
+                // fall through to warn
+            }
+        }
+        logger_js_1.logger.warn({ err: error instanceof Error ? error.message : String(error) }, "optional @firecrawl/anydoc not available — office/PDF documents will be skipped");
+        anydocModule = null;
+    }
+    return anydocModule;
+}
+/** Test hook: reset optional-dep load cache. */
+function resetDocumentConverterCache() {
+    anydocLoadAttempted = false;
+    anydocModule = null;
+}
+/** Test hook: inject a fake converter module. */
+function setDocumentConverterForTests(mod) {
+    anydocLoadAttempted = true;
+    anydocModule = mod;
+}
+/**
+ * Convert an office/PDF file to Markdown.
+ * Returns skippedReason when the optional converter is missing or conversion fails softly.
+ */
+async function convertDocumentToMarkdown(absPath, bytes) {
+    const anydoc = loadAnydoc();
+    if (!anydoc?.toMarkdown && !anydoc?.toMarkdownBytes) {
+        return {
+            markdown: "",
+            converter: "unavailable",
+            skippedReason: "optional-dependency-missing:@firecrawl/anydoc",
+        };
+    }
+    try {
+        let markdown = "";
+        if (anydoc.toMarkdown) {
+            markdown = await anydoc.toMarkdown(absPath);
+        }
+        else if (anydoc.toMarkdownBytes && bytes) {
+            markdown = await anydoc.toMarkdownBytes(bytes);
+        }
+        else if (anydoc.toMarkdownBytes) {
+            const { readFileSync } = await import("node:fs");
+            markdown = await anydoc.toMarkdownBytes(readFileSync(absPath));
+        }
+        const trimmed = markdown?.trim() ?? "";
+        if (!trimmed) {
+            return {
+                markdown: "",
+                converter: "anydoc",
+                skippedReason: "empty-markdown",
+            };
+        }
+        return { markdown: trimmed, converter: "anydoc" };
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : undefined;
+        const message = error instanceof Error ? error.message : String(error);
+        logger_js_1.logger.warn({ path: absPath, code, message }, "document conversion failed");
+        return {
+            markdown: "",
+            converter: "anydoc",
+            skippedReason: code ? `convert-error:${code}` : `convert-error:${message.slice(0, 120)}`,
+        };
+    }
+}
+//# sourceMappingURL=document-convert.js.map

package/dist/graph/document-convert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-convert.js","sourceRoot":"","sources":["../../src/graph/document-convert.ts"],"names":[],"mappings":"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"}

package/dist/graph/document-semantic-bridge.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Bridge work items for document semantic extraction after structural indexing.
+ * Structure (headings/chunks/links) comes from Markdown conversion; deep
+ * semantics are delegated to the host agent via ATP/bridge.
+ */
+import type { AgentWorkItem } from "../core/agent-delegation.js";
+export interface DocumentSemanticTarget {
+    relPath: string;
+    /** Short structural summary (title / top headings). */
+    outline: string;
+    /** Truncated markdown body for the agent prompt. */
+    excerpt: string;
+}
+/**
+ * Build optional bridge work items so the host agent extracts entities,
+ * claims, and a concise semantic summary, then submits via graphflow_insight.
+ */
+export declare function buildDocumentSemanticWorkItems(docs: DocumentSemanticTarget[], options?: {
+    maxDocs?: number;
+}): AgentWorkItem[];
+/** Build a short outline string from markdown headings. */
+export declare function outlineFromMarkdown(markdown: string, maxHeadings?: number): string;
+//# sourceMappingURL=document-semantic-bridge.d.ts.map

package/dist/graph/document-semantic-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-semantic-bridge.d.ts","sourceRoot":"","sources":["../../src/graph/document-semantic-bridge.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAEjE,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,sBAAsB,EAAE,EAC9B,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,aAAa,EAAE,CAmCjB;AAED,2DAA2D;AAC3D,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,SAAK,GAAG,MAAM,CAU9E"}

package/dist/graph/document-semantic-bridge.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Bridge work items for document semantic extraction after structural indexing.
+ * Structure (headings/chunks/links) comes from Markdown conversion; deep
+ * semantics are delegated to the host agent via ATP/bridge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDocumentSemanticWorkItems = buildDocumentSemanticWorkItems;
+exports.outlineFromMarkdown = outlineFromMarkdown;
+/**
+ * Build optional bridge work items so the host agent extracts entities,
+ * claims, and a concise semantic summary, then submits via graphflow_insight.
+ */
+function buildDocumentSemanticWorkItems(docs, options) {
+    const maxDocs = options?.maxDocs ?? 5;
+    const selected = docs.slice(0, maxDocs);
+    if (selected.length === 0) {
+        return [];
+    }
+    return selected.map((doc, index) => ({
+        id: `document-semantic-${index + 1}`,
+        kind: "document-semantic",
+        optional: true,
+        expectedFormat: "json",
+        prompt: [
+            `Document semantic extraction for: ${doc.relPath}`,
+            "",
+            "Structural outline (already indexed as graph sections/chunks):",
+            doc.outline,
+            "",
+            "Excerpt:",
+            doc.excerpt.slice(0, 4000),
+            "",
+            "Extract KEY information and semantics for the knowledge graph.",
+            "Return JSON only. Then submit via graphflow_insight(mode=\"submit\") with this id.",
+        ].join("\n"),
+        responseSchema: {
+            relPath: `string — echo exactly: ${doc.relPath}`,
+            title: "string — document title",
+            summary: "string — 2-4 sentence semantic summary",
+            keyEntities: "string[] — people/orgs/systems/APIs/modules → Concept nodes",
+            requirements: "string[] — normative requirements (preferred over keyClaims)",
+            keyClaims: "string[] — fallback facts/requirements if requirements omitted",
+            relatedCodeHints: "string[] — code symbol names or relative file paths to link",
+            tags: "string[] — short topic tags",
+        },
+    }));
+}
+/** Build a short outline string from markdown headings. */
+function outlineFromMarkdown(markdown, maxHeadings = 12) {
+    const headings = markdown
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => /^#{1,3}\s+/.test(line))
+        .slice(0, maxHeadings);
+    if (headings.length === 0) {
+        return "(no headings — body chunk indexed)";
+    }
+    return headings.join("\n");
+}
+//# sourceMappingURL=document-semantic-bridge.js.map

package/dist/graph/document-semantic-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-semantic-bridge.js","sourceRoot":"","sources":["../../src/graph/document-semantic-bridge.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAgBH,wEAsCC;AAGD,kDAUC;AAvDD;;;GAGG;AACH,SAAgB,8BAA8B,CAC5C,IAA8B,EAC9B,OAA8B;IAE9B,MAAM,OAAO,GAAG,OAAO,EAAE,OAAO,IAAI,CAAC,CAAC;IACtC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACxC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACnC,EAAE,EAAE,qBAAqB,KAAK,GAAG,CAAC,EAAE;QACpC,IAAI,EAAE,mBAA4B;QAClC,QAAQ,EAAE,IAAI;QACd,cAAc,EAAE,MAAe;QAC/B,MAAM,EAAE;YACN,qCAAqC,GAAG,CAAC,OAAO,EAAE;YAClD,EAAE;YACF,gEAAgE;YAChE,GAAG,CAAC,OAAO;YACX,EAAE;YACF,UAAU;YACV,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC;YAC1B,EAAE;YACF,gEAAgE;YAChE,oFAAoF;SACrF,CAAC,IAAI,CAAC,IAAI,CAAC;QACZ,cAAc,EAAE;YACd,OAAO,EAAE,0BAA0B,GAAG,CAAC,OAAO,EAAE;YAChD,KAAK,EAAE,yBAAyB;YAChC,OAAO,EAAE,wCAAwC;YACjD,WAAW,EAAE,6DAA6D;YAC1E,YAAY,EAAE,8DAA8D;YAC5E,SAAS,EAAE,gEAAgE;YAC3E,gBAAgB,EAAE,6DAA6D;YAC/E,IAAI,EAAE,6BAA6B;SACpC;KACF,CAAC,CAAC,CAAC;AACN,CAAC;AAED,2DAA2D;AAC3D,SAAgB,mBAAmB,CAAC,QAAgB,EAAE,WAAW,GAAG,EAAE;IACpE,MAAM,QAAQ,GAAG,QAAQ;SACtB,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACzC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IACzB,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,oCAAoC,CAAC;IAC9C,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/graph/document-semantic-ingest.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Upsert document-domain Concept/Requirement nodes and cross-layer edges
+ * after a document-semantic bridge submission.
+ *
+ * Logical Engineering KG (single store):
+ *   code ←documents/implements→ doc ←derived_from→ experience(insight)
+ */
+import type { GraphClient } from "./client-factory.js";
+import type { GraphEdge, GraphNode } from "../core/types.js";
+export interface DocumentSemanticPayload {
+    relPath?: string;
+    title?: string;
+    summary?: string;
+    keyEntities?: string[];
+    keyClaims?: string[];
+    /** Prefer explicit requirements when present; else keyClaims are used. */
+    requirements?: string[];
+    relatedCodeHints?: string[];
+    tags?: string[];
+}
+export interface DocumentSemanticIngestResult {
+    conceptIds: string[];
+    requirementIds: string[];
+    edgeCount: number;
+    linkedCodeNodeIds: string[];
+}
+export declare function parseDocumentSemanticPayload(parsed: Record<string, unknown>): DocumentSemanticPayload;
+/**
+ * Resolve relatedCodeHints against existing File/Symbol nodes.
+ * Paths prefer file: ids; bare names match Symbol metadata.name or content.
+ */
+export declare function resolveCodeHintTargets(hints: string[], nodes: GraphNode[], maxLinks?: number): string[];
+/**
+ * Build Concept/Requirement nodes + cross-layer edges from a bridge payload.
+ */
+export declare function buildDocumentSemanticGraphFragment(payload: DocumentSemanticPayload, options: {
+    insightNodeId: string;
+    existingNodes?: GraphNode[];
+    maxConcepts?: number;
+    maxRequirements?: number;
+}): {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    linkedCodeNodeIds: string[];
+};
+export declare function ingestDocumentSemanticInsight(client: GraphClient, parsed: Record<string, unknown>, insightNodeId: string): Promise<DocumentSemanticIngestResult>;
+export declare function isDocumentSemanticWorkItemId(workItemId: string): boolean;
+//# sourceMappingURL=document-semantic-ingest.d.ts.map

package/dist/graph/document-semantic-ingest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-semantic-ingest.d.ts","sourceRoot":"","sources":["../../src/graph/document-semantic-ingest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7D,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,4BAA4B;IAC3C,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAeD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,uBAAuB,CAqBzB;AAUD;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EAAE,EACf,KAAK,EAAE,SAAS,EAAE,EAClB,QAAQ,SAAK,GACZ,MAAM,EAAE,CAkEV;AAED;;GAEG;AACH,wBAAgB,kCAAkC,CAChD,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE;IACP,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,SAAS,EAAE,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GACA;IAAE,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,KAAK,EAAE,SAAS,EAAE,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAiGzE;AAED,wBAAsB,6BAA6B,CACjD,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,4BAA4B,CAAC,CAqBvC;AAED,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE"}

package/dist/graph/document-semantic-ingest.js

@@ -0,0 +1,229 @@
+"use strict";
+/**
+ * Upsert document-domain Concept/Requirement nodes and cross-layer edges
+ * after a document-semantic bridge submission.
+ *
+ * Logical Engineering KG (single store):
+ *   code ←documents/implements→ doc ←derived_from→ experience(insight)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDocumentSemanticPayload = parseDocumentSemanticPayload;
+exports.resolveCodeHintTargets = resolveCodeHintTargets;
+exports.buildDocumentSemanticGraphFragment = buildDocumentSemanticGraphFragment;
+exports.ingestDocumentSemanticInsight = ingestDocumentSemanticInsight;
+exports.isDocumentSemanticWorkItemId = isDocumentSemanticWorkItemId;
+const hash_js_1 = require("../utils/hash.js");
+function asString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => asString(item))
+        .filter((item) => item.length > 0);
+}
+function parseDocumentSemanticPayload(parsed) {
+    const payload = {
+        keyEntities: asStringArray(parsed.keyEntities),
+        keyClaims: asStringArray(parsed.keyClaims),
+        requirements: asStringArray(parsed.requirements),
+        relatedCodeHints: asStringArray(parsed.relatedCodeHints),
+        tags: asStringArray(parsed.tags),
+    };
+    const relPath = asString(parsed.relPath);
+    if (relPath) {
+        payload.relPath = relPath;
+    }
+    const title = asString(parsed.title);
+    if (title) {
+        payload.title = title;
+    }
+    const summary = asString(parsed.summary);
+    if (summary) {
+        payload.summary = summary;
+    }
+    return payload;
+}
+function conceptNodeId(relPath, name) {
+    return `concept:${(0, hash_js_1.hashText)(`${relPath}|${name.toLowerCase()}`)}`;
+}
+function requirementNodeId(relPath, claim) {
+    return `requirement:${(0, hash_js_1.hashText)(`${relPath}|${claim.toLowerCase()}`)}`;
+}
+/**
+ * Resolve relatedCodeHints against existing File/Symbol nodes.
+ * Paths prefer file: ids; bare names match Symbol metadata.name or content.
+ */
+function resolveCodeHintTargets(hints, nodes, maxLinks = 12) {
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const symbols = nodes.filter((n) => n.type === "Symbol");
+    const files = nodes.filter((n) => n.type === "File");
+    const found = [];
+    const seen = new Set();
+    const push = (id) => {
+        if (seen.has(id) || found.length >= maxLinks) {
+            return;
+        }
+        if (!byId.has(id)) {
+            return;
+        }
+        seen.add(id);
+        found.push(id);
+    };
+    for (const raw of hints) {
+        if (found.length >= maxLinks) {
+            break;
+        }
+        const hint = raw.trim();
+        if (!hint) {
+            continue;
+        }
+        if (hint.startsWith("file:") || hint.startsWith("symbol:")) {
+            push(hint);
+            continue;
+        }
+        const normalized = hint.replace(/\\/g, "/");
+        const asFileId = `file:${normalized.replace(/^\.\//, "")}`;
+        if (byId.has(asFileId)) {
+            push(asFileId);
+            continue;
+        }
+        const lower = normalized.toLowerCase();
+        const fileHit = files.find((f) => {
+            const path = f.id.slice("file:".length).toLowerCase();
+            return path === lower || path.endsWith(`/${lower}`) || path.endsWith(lower);
+        });
+        if (fileHit) {
+            push(fileHit.id);
+            continue;
+        }
+        const name = normalized.includes("/")
+            ? (normalized.split("/").pop() ?? normalized)
+            : normalized;
+        const nameLower = name.toLowerCase().replace(/\.(ts|tsx|js|jsx|py|go|rs|java)$/i, "");
+        const symbolHit = symbols.find((s) => {
+            const metaName = asString(s.metadata?.name).toLowerCase();
+            if (metaName && metaName === nameLower) {
+                return true;
+            }
+            return s.content.toLowerCase().includes(nameLower);
+        });
+        if (symbolHit) {
+            push(symbolHit.id);
+        }
+    }
+    return found;
+}
+/**
+ * Build Concept/Requirement nodes + cross-layer edges from a bridge payload.
+ */
+function buildDocumentSemanticGraphFragment(payload, options) {
+    const relPath = payload.relPath?.trim();
+    if (!relPath) {
+        return { nodes: [], edges: [], linkedCodeNodeIds: [] };
+    }
+    const maxConcepts = options.maxConcepts ?? 12;
+    const maxRequirements = options.maxRequirements ?? 12;
+    const fileNodeId = `file:${relPath}`;
+    const entities = (payload.keyEntities ?? []).slice(0, maxConcepts);
+    const requirements = ((payload.requirements?.length ? payload.requirements : payload.keyClaims) ?? []).slice(0, maxRequirements);
+    const nodes = [];
+    const edges = [];
+    const conceptIds = [];
+    const requirementIds = [];
+    for (const name of entities) {
+        const id = conceptNodeId(relPath, name);
+        conceptIds.push(id);
+        nodes.push({
+            id,
+            type: "Concept",
+            content: name,
+            metadata: {
+                domain: "doc",
+                kind: "concept",
+                sourcePath: relPath,
+                title: payload.title,
+                tags: payload.tags ?? [],
+            },
+        });
+        edges.push({ from: fileNodeId, to: id, relation: "documents" });
+        edges.push({ from: id, to: fileNodeId, relation: "derived_from" });
+        edges.push({ from: id, to: options.insightNodeId, relation: "derived_from" });
+    }
+    for (const claim of requirements) {
+        const id = requirementNodeId(relPath, claim);
+        requirementIds.push(id);
+        nodes.push({
+            id,
+            type: "Requirement",
+            content: claim.slice(0, 500),
+            metadata: {
+                domain: "doc",
+                kind: "requirement",
+                sourcePath: relPath,
+                title: payload.title,
+                tags: payload.tags ?? [],
+            },
+        });
+        edges.push({ from: fileNodeId, to: id, relation: "documents" });
+        edges.push({ from: id, to: fileNodeId, relation: "derived_from" });
+        edges.push({ from: id, to: options.insightNodeId, relation: "derived_from" });
+    }
+    // Optional: enrich the File node summary via a lightweight Decision-adjacent metadata node —
+    // skip; File already exists from indexing.
+    const linkedCodeNodeIds = resolveCodeHintTargets(payload.relatedCodeHints ?? [], options.existingNodes ?? []);
+    for (const codeId of linkedCodeNodeIds) {
+        for (const reqId of requirementIds) {
+            edges.push({ from: codeId, to: reqId, relation: "implements" });
+        }
+        edges.push({ from: fileNodeId, to: codeId, relation: "references" });
+    }
+    // If summary present, attach as a Concept titled by document title
+    const title = payload.title?.trim();
+    const summary = payload.summary?.trim();
+    if (title && summary && !entities.some((e) => e.toLowerCase() === title.toLowerCase())) {
+        const id = conceptNodeId(relPath, `title:${title}`);
+        nodes.push({
+            id,
+            type: "Concept",
+            content: `${title} — ${summary}`.slice(0, 500),
+            metadata: {
+                domain: "doc",
+                kind: "document-summary",
+                sourcePath: relPath,
+                title,
+                tags: payload.tags ?? [],
+            },
+        });
+        edges.push({ from: fileNodeId, to: id, relation: "documents" });
+        edges.push({ from: id, to: fileNodeId, relation: "derived_from" });
+        edges.push({ from: id, to: options.insightNodeId, relation: "derived_from" });
+    }
+    return { nodes, edges, linkedCodeNodeIds };
+}
+async function ingestDocumentSemanticInsight(client, parsed, insightNodeId) {
+    const payload = parseDocumentSemanticPayload(parsed);
+    const snapshot = client.readSnapshot?.();
+    const fragment = buildDocumentSemanticGraphFragment(payload, {
+        insightNodeId,
+        existingNodes: snapshot?.nodes ?? [],
+    });
+    if (fragment.nodes.length > 0) {
+        await client.upsertNodes(fragment.nodes);
+    }
+    if (fragment.edges.length > 0 && client.upsertEdges) {
+        await client.upsertEdges(fragment.edges);
+    }
+    return {
+        conceptIds: fragment.nodes.filter((n) => n.type === "Concept").map((n) => n.id),
+        requirementIds: fragment.nodes.filter((n) => n.type === "Requirement").map((n) => n.id),
+        edgeCount: fragment.edges.length,
+        linkedCodeNodeIds: fragment.linkedCodeNodeIds,
+    };
+}
+function isDocumentSemanticWorkItemId(workItemId) {
+    return workItemId.startsWith("document-semantic");
+}
+//# sourceMappingURL=document-semantic-ingest.js.map

package/dist/graph/document-semantic-ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-semantic-ingest.js","sourceRoot":"","sources":["../../src/graph/document-semantic-ingest.ts"],"names":[],"mappings":"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"}

package/dist/graph/episode-engineering-links.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Link failure (or any) episode Decision nodes to Engineering KG
+ * Requirement / Concept / code nodes via derived_from edges.
+ *
+ * Mirrors document-semantic provenance style (experience ↔ eng nodes),
+ * with direction episode → derived_from → requirement|concept|code.
+ */
+import type { GraphClient } from "./client-factory.js";
+import type { GraphEdge } from "../core/types.js";
+export type EngineeringLinkHints = {
+    requirementIds?: string[];
+    conceptIds?: string[];
+    /** File paths, symbol names, or file:/symbol: ids resolved against the graph. */
+    codeHints?: string[];
+};
+export type LinkEpisodeResult = {
+    episodeId: string;
+    edgeCount: number;
+    edges: GraphEdge[];
+    linkedRequirementIds: string[];
+    linkedConceptIds: string[];
+    linkedCodeNodeIds: string[];
+};
+/**
+ * Upsert `derived_from` edges from an episode to Requirement / Concept nodes
+ * (and optionally to File/Symbol nodes resolved from codeHints).
+ */
+export declare function linkEpisodeToEngineeringNodes(graphClient: GraphClient, episodeId: string, hints: EngineeringLinkHints): Promise<LinkEpisodeResult>;
+//# sourceMappingURL=episode-engineering-links.d.ts.map

package/dist/graph/episode-engineering-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episode-engineering-links.d.ts","sourceRoot":"","sources":["../../src/graph/episode-engineering-links.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGlD,MAAM,MAAM,oBAAoB,GAAG;IACjC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B,CAAC;AAmBF;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,iBAAiB,CAAC,CAkC5B"}

package/dist/graph/episode-engineering-links.js

@@ -0,0 +1,63 @@
+"use strict";
+/**
+ * Link failure (or any) episode Decision nodes to Engineering KG
+ * Requirement / Concept / code nodes via derived_from edges.
+ *
+ * Mirrors document-semantic provenance style (experience ↔ eng nodes),
+ * with direction episode → derived_from → requirement|concept|code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.linkEpisodeToEngineeringNodes = linkEpisodeToEngineeringNodes;
+const document_semantic_ingest_js_1 = require("./document-semantic-ingest.js");
+function uniqueNonEmpty(ids) {
+    if (!ids || ids.length === 0) {
+        return [];
+    }
+    const seen = new Set();
+    const out = [];
+    for (const raw of ids) {
+        const id = typeof raw === "string" ? raw.trim() : "";
+        if (!id || seen.has(id)) {
+            continue;
+        }
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+/**
+ * Upsert `derived_from` edges from an episode to Requirement / Concept nodes
+ * (and optionally to File/Symbol nodes resolved from codeHints).
+ */
+async function linkEpisodeToEngineeringNodes(graphClient, episodeId, hints) {
+    const linkedRequirementIds = uniqueNonEmpty(hints.requirementIds);
+    const linkedConceptIds = uniqueNonEmpty(hints.conceptIds);
+    let linkedCodeNodeIds = [];
+    const codeHints = uniqueNonEmpty(hints.codeHints);
+    if (codeHints.length > 0) {
+        const snapshot = graphClient.readSnapshot?.();
+        linkedCodeNodeIds = (0, document_semantic_ingest_js_1.resolveCodeHintTargets)(codeHints, snapshot?.nodes ?? []);
+    }
+    const edges = [];
+    for (const to of linkedRequirementIds) {
+        edges.push({ from: episodeId, to, relation: "derived_from" });
+    }
+    for (const to of linkedConceptIds) {
+        edges.push({ from: episodeId, to, relation: "derived_from" });
+    }
+    for (const to of linkedCodeNodeIds) {
+        edges.push({ from: episodeId, to, relation: "derived_from" });
+    }
+    if (edges.length > 0 && graphClient.upsertEdges) {
+        await graphClient.upsertEdges(edges);
+    }
+    return {
+        episodeId,
+        edgeCount: edges.length,
+        edges,
+        linkedRequirementIds,
+        linkedConceptIds,
+        linkedCodeNodeIds,
+    };
+}
+//# sourceMappingURL=episode-engineering-links.js.map

package/dist/graph/episode-engineering-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"episode-engineering-links.js","sourceRoot":"","sources":["../../src/graph/episode-engineering-links.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AA2CH,sEAsCC;AA7ED,+EAAuE;AAkBvE,SAAS,cAAc,CAAC,GAAyB;IAC/C,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,GAAG,IAAI,GAAG,EAAE,CAAC;QACtB,MAAM,EAAE,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;YACxB,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACb,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,6BAA6B,CACjD,WAAwB,EACxB,SAAiB,EACjB,KAA2B;IAE3B,MAAM,oBAAoB,GAAG,cAAc,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IAClE,MAAM,gBAAgB,GAAG,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC1D,IAAI,iBAAiB,GAAa,EAAE,CAAC;IAErC,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,QAAQ,GAAG,WAAW,CAAC,YAAY,EAAE,EAAE,CAAC;QAC9C,iBAAiB,GAAG,IAAA,oDAAsB,EAAC,SAAS,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,KAAK,MAAM,EAAE,IAAI,oBAAoB,EAAE,CAAC;QACtC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,gBAAgB,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,KAAK,MAAM,EAAE,IAAI,iBAAiB,EAAE,CAAC;QACnC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,WAAW,CAAC,WAAW,EAAE,CAAC;QAChD,MAAM,WAAW,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACvC,CAAC;IAED,OAAO;QACL,SAAS;QACT,SAAS,EAAE,KAAK,CAAC,MAAM;QACvB,KAAK;QACL,oBAAoB;QACpB,gBAAgB;QAChB,iBAAiB;KAClB,CAAC;AACJ,CAAC"}