@rubytech/create-maxy 1.0.708 → 1.0.710

package/payload/platform/plugins/memory/mcp/dist/tools/memory-ingest.js

@@ -3,33 +3,51 @@ import { embed, embedBatch } from "../lib/embeddings.js";
 import { extractCache } from "./memory-ingest-extract.js";
 import { deleteDocumentChildren } from "../lib/document-hierarchy.js";
 import { restoreNode } from "../../../../../lib/graph-trash/dist/index.js";
+import { IDENTITY_SECTION_KINDS, STRUCTURAL_SECTION_KINDS, CONTRACT_SECTION_KINDS, STANDALONE_NODE_KINDS, SECTION_KIND_OTHER, } from "../lib/llm-classifier.js";
 // ---------------------------------------------------------------------------
-// Typed-node document ingestion (Task 737).
+// Single-Section document ingestion (Task 740, replacing Task 737's typed-vs-
+// UNMAPPED fork).
 //
 // CACHE LOOKUP --> MERGE/REVIVE DOC --> CLEANUP CHILDREN --> EMBED --> WRITE
-//   (by attachmentId)  KnowledgeDocument    delete prior         batch    typed nodes
-//                      (idempotent)         Section/Chunk/typed  Ollama   + anchor edges
-//                                                                         + REFERENCES
+//   (by attachmentId)  KnowledgeDocument    delete prior         batch    Section nodes
+//                      (idempotent)         Section/Chunk/typed  Ollama   + secondary labels
+//                                                                         + NEXT chain
+//                                                                         + anchor edges
+//                                                                         + related entities
+//                                                                         + KD-level edges
 //
-// Each classified section becomes either:
-//   - a typed graph node (Position, Service, Credential, etc.) anchored to
-//     UserProfile / LocalBusiness / Person / Organization via the natural
-//     ontology edge, plus a (KnowledgeDocument)-[:REFERENCES]->(typed) link
-//     for retrieval, plus optional related-entity nodes (e.g. Position's
-//     employer Organization, MERGEd by name).
-//   - a generic :Section node (UNMAPPED fallback) hanging off the document
-//     via the legacy (KnowledgeDocument)-[:HAS_SECTION] edge, with optional
-//     :Chunk overflow when the body exceeds MAX_CHUNK_SIZE.
+// Every classified section produces ONE `:Section` node. When the classifier
+// recognises the kind (Position/Education/Chapter/Parties/etc.), the same
+// node carries a secondary label (`:Section:Position`) and any structured
+// properties; identity-kind anchor edges go to the multi-labeled node
+// directly, killing the parallel Section-vs-typed-node concept.
+//
+// Special-case writers fire for two contract-clause kinds:
+//   * Parties:     `(:KnowledgeDocument)-[:PARTY]->(:Person|:Organization)` from documentEdges.
+//   * Definitions: `(:Section:Definitions)-[:DEFINES]->(:DefinedTerm)` from related entries.
+//
+// `:Chunk` is gone. Sections carry their body directly. If a body legitimately
+// exceeds Neo4j's property limit, that is a classifier-split-the-section
+// concern, not a writer problem.
 //
 // Provenance properties (createdByAgent, createdBySession, source,
-// sourceDocumentId) stamp every node and edge the skill creates so the
-// re-ingest cleanup can find and replace them deterministically.
+// sourceDocumentId) stamp every node and edge so re-ingest cleanup finds
+// them deterministically.
 // ---------------------------------------------------------------------------
-const MAX_CHUNK_SIZE = 2000;
 const PREVIEW_LENGTH = 150;
-const UNMAPPED = "UNMAPPED";
 const PROVENANCE_AGENT = "document-ingest";
 const PROVENANCE_SOURCE = "document";
+/** Identity-kind anchor edge writer set (UserProfile → Section:Kind). */
+const IDENTITY_KINDS_SET = new Set(IDENTITY_SECTION_KINDS);
+/** Standalone (non-Section) node kinds (currently just Project). */
+const STANDALONE_KINDS_SET = new Set(STANDALONE_NODE_KINDS);
+/** All section-shaped kinds — anything that becomes a `:Section` node. */
+const SECTION_LABEL_KINDS = new Set([
+    ...IDENTITY_SECTION_KINDS,
+    ...STRUCTURAL_SECTION_KINDS,
+    ...CONTRACT_SECTION_KINDS,
+    SECTION_KIND_OTHER,
+]);
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -38,15 +56,6 @@ function normaliseKeywords(arr) {
         return [];
     return arr.map((k) => k.toLowerCase().trim()).filter(Boolean);
 }
-function chunkBody(body) {
-    if (body.length <= MAX_CHUNK_SIZE)
-        return [body];
-    const chunks = [];
-    for (let i = 0; i < body.length; i += MAX_CHUNK_SIZE) {
-        chunks.push(body.slice(i, i + MAX_CHUNK_SIZE));
-    }
-    return chunks;
-}
 /**
  * Identifying property for MERGE on a related node by kind.
  * Choose a stable, human-recognisable key per label so the same real-world
@@ -78,11 +87,17 @@ function mergeKeyFor(kind, properties) {
             return null;
     }
 }
+function bumpKind(breakdown, kind) {
+    breakdown[kind] = (breakdown[kind] ?? 0) + 1;
+}
+function bumpEdge(breakdown, edgeType) {
+    breakdown[edgeType] = (breakdown[edgeType] ?? 0) + 1;
+}
 // ---------------------------------------------------------------------------
 // Main entry point
 // ---------------------------------------------------------------------------
 export async function memoryIngest(params) {
-    const { accountId, attachmentId, documentSummary, anchorNodeId, anchorLabel, sections, scope, sourceUrl, sourceType, documentKeywords: rawDocKeywords, userKeywords: rawUserKeywords, sessionId, } = params;
+    const { accountId, attachmentId, documentSummary, anchorNodeId, anchorLabel, sections, documentEdges = [], orphanCandidates = [], scope, sourceUrl, sourceType, documentKeywords: rawDocKeywords, userKeywords: rawUserKeywords, sessionId, } = params;
     if (!scope) {
         throw new Error("scope is required — valid values: 'public', 'shared', 'admin', 'user:{identifier}'");
     }
@@ -116,23 +131,23 @@ export async function memoryIngest(params) {
     const embeddings = await embedBatch(textsToEmbed);
     log("embedded", `${embeddings.length} vectors`);
     const docEmbedding = embeddings[0];
-    const session = getSession();
+    const dbSession = getSession();
     let documentNodeId = "";
-    let typedCount = 0;
-    let unmappedCount = 0;
-    let chunkCount = 0;
-    let entityLinks = 0;
+    const kindBreakdown = {};
+    const edgeBreakdown = {};
+    let relatedCount = 0;
+    let standaloneCount = 0;
     try {
         // 2. Trash-revival (Task 576) — restore a soft-deleted KnowledgeDocument
         //    with this attachmentId so MERGE finds the existing node.
-        const trashedDoc = await session.run(`MATCH (d:KnowledgeDocument:Trashed)
+        const trashedDoc = await dbSession.run(`MATCH (d:KnowledgeDocument:Trashed)
        WHERE d.accountId = $accountId
          AND d._trashedKeys IS NOT NULL
          AND d._trashedKeys CONTAINS $attachmentId
        RETURN elementId(d) AS eid LIMIT 1`, { accountId, attachmentId });
         if (trashedDoc.records.length > 0) {
             const eid = trashedDoc.records[0].get("eid");
-            await restoreNode({ session, accountId, elementId: eid });
+            await restoreNode({ session: dbSession, accountId, elementId: eid });
             log("revived", `restored trashed KnowledgeDocument elementId=${eid}`);
         }
         // 3. MERGE the KnowledgeDocument parent. Optional fields (sourceUrl,
@@ -153,7 +168,7 @@ export async function memoryIngest(params) {
             optionalParams.keywords = keywords;
         }
         const optionalSetClause = optionalSets.length > 0 ? ", " + optionalSets.join(", ") : "";
-        const docResult = await session.run(`MERGE (d:KnowledgeDocument { attachmentId: $attachmentId })
+        const docResult = await dbSession.run(`MERGE (d:KnowledgeDocument { attachmentId: $attachmentId })
        SET d.accountId      = $accountId,
            d.name           = $filename,
            d.encodingFormat = $mimeType,
@@ -179,21 +194,21 @@ export async function memoryIngest(params) {
             ...optionalParams,
         });
         documentNodeId = docResult.records[0].get("nodeId");
-        // 4. Cleanup prior children (idempotent re-ingest). Removes generic
-        //    :Section/Chunk fallbacks and typed nodes that originated from this
-        //    document. MERGEd related nodes (Organizations, Persons) are spared.
-        const cleanup = await deleteDocumentChildren(attachmentId, session);
-        if (cleanup.sections > 0 ||
-            cleanup.chunks > 0 ||
-            cleanup.typed > 0 ||
-            cleanup.references > 0) {
+        console.error(`[memory-ingest] KnowledgeDocument.name=${JSON.stringify(filename)} attachmentId=${attachmentId.slice(0, 8)} docId=${documentNodeId.slice(0, 12)}`);
+        // 4. Cleanup prior children (idempotent re-ingest). Removes Section nodes
+        //    (any secondary label) and any standalone nodes stamped with this
+        //    attachmentId. MERGEd related entities (Organizations, Persons) are spared.
+        const cleanup = await deleteDocumentChildren(attachmentId, dbSession);
+        if (cleanup.sections > 0 || cleanup.chunks > 0 || cleanup.typed > 0 || cleanup.references > 0) {
             log("cleanup", `deleted ${cleanup.sections} sections, ${cleanup.chunks} chunks, ${cleanup.typed} typed, ${cleanup.references} references`);
         }
-        // 5. Per-section writes.
+        // 5. Per-section writes. Track the previous section's elementId so we can
+        //    chain (:Section)-[:NEXT]->(:Section) in reading order.
+        let previousSectionId = null;
         for (let i = 0; i < sections.length; i++) {
             const section = sections[i];
             const bodyEmbedding = embeddings[i + 1]; // +1 because index 0 is docEmbedding
-            const sectionParams = {
+            const baseProps = {
                 accountId,
                 title: section.title,
                 body: section.body,
@@ -209,172 +224,91 @@ export async function memoryIngest(params) {
                 source: PROVENANCE_SOURCE,
                 sourceDocumentId: attachmentId,
             };
-            if (section.kind === UNMAPPED) {
-                // 5a. UNMAPPED: generic :Section + (KnowledgeDocument)-[:HAS_SECTION]
-                const sectionResult = await session.run(`CREATE (s:Section {
-             accountId:        $accountId,
-             title:            $title,
-             body:             $body,
-             summary:          $bodyPreview,
-             position:         $position,
-             scope:            $scope,
-             embedding:        $embedding,
-             createdAt:        $createdAt,
-             updatedAt:        $updatedAt,
-             createdByAgent:   $createdByAgent,
-             createdBySource:  $createdBySource,
-             createdBySession: $createdBySession,
-             source:           $source,
-             sourceDocumentId: $sourceDocumentId
-           })
-           WITH s
-           MATCH (d:KnowledgeDocument) WHERE elementId(d) = $docId
-           CREATE (d)-[:HAS_SECTION]->(s)
-           RETURN elementId(s) AS nodeId`, { ...sectionParams, docId: documentNodeId });
-                const sectionId = sectionResult.records[0].get("nodeId");
-                // Body overflow → :Chunk children
-                if (section.body.length > MAX_CHUNK_SIZE) {
-                    const overflowChunks = chunkBody(section.body);
-                    const overflowEmbeddings = await embedBatch(overflowChunks);
-                    for (let ci = 0; ci < overflowChunks.length; ci++) {
-                        await session.run(`MATCH (s:Section) WHERE elementId(s) = $sectionId
-               CREATE (s)-[:HAS_CHUNK]->(c:Chunk {
-                 accountId:        $accountId,
-                 content:          $content,
-                 summary:          $summary,
-                 position:         $position,
-                 scope:            $scope,
-                 embedding:        $embedding,
-                 createdAt:        $createdAt,
-                 updatedAt:        $updatedAt,
-                 createdByAgent:   $createdByAgent,
-                 createdBySource:  $createdBySource,
-                 createdBySession: $createdBySession,
-                 source:           $source,
-                 sourceDocumentId: $sourceDocumentId
-               })`, {
-                            sectionId,
-                            accountId,
-                            content: overflowChunks[ci],
-                            summary: overflowChunks[ci].slice(0, PREVIEW_LENGTH),
-                            position: ci,
-                            scope,
-                            embedding: overflowEmbeddings[ci],
-                            createdAt: now,
-                            updatedAt: now,
-                            createdByAgent: PROVENANCE_AGENT,
-                            createdBySource: PROVENANCE_AGENT,
-                            createdBySession: sessionId ?? "",
-                            source: PROVENANCE_SOURCE,
-                            sourceDocumentId: attachmentId,
-                        });
-                        chunkCount += 1;
+            // 5a. Standalone node kind (currently just Project) — no `:Section` label.
+            if (STANDALONE_KINDS_SET.has(section.kind)) {
+                const standaloneId = await writeStandaloneNode(dbSession, section, baseProps, anchorNodeId, anchorLabel, attachmentId, sessionId ?? "", now);
+                standaloneCount += 1;
+                bumpKind(kindBreakdown, section.kind);
+                if (section.anchorEdge)
+                    bumpEdge(edgeBreakdown, section.anchorEdge.type);
+                previousSectionId = null; // standalone breaks the section chain
+                // related entities for standalone (e.g. Project UNDER Organization)
+                if (section.related && section.related.length > 0) {
+                    for (const related of section.related) {
+                        await writeRelatedAndEdge(dbSession, standaloneId, related, accountId, now, sessionId ?? "", attachmentId);
+                        relatedCount += 1;
+                        bumpEdge(edgeBreakdown, related.edge.type);
                     }
                 }
-                unmappedCount += 1;
-                console.error(`[document-ingest] unmapped-section title="${section.title}" chars=${section.body.length}`);
                 continue;
             }
-            // 5b. Typed kind — write the typed node, anchor edge, related nodes,
-            //     and the document REFERENCES link.
-            // Build the typed-node properties: classifier-supplied properties
-            // overlaid on top of the system fields, with system fields winning.
-            const typedProps = {
+            // 5b. Section-shaped kind (everything else, including Other). One `:Section`
+            //     node with optional secondary label.
+            const isKnownSectionKind = SECTION_LABEL_KINDS.has(section.kind);
+            const sectionLabels = isKnownSectionKind && section.kind !== SECTION_KIND_OTHER
+                ? [`Section`, section.kind]
+                : section.kind === SECTION_KIND_OTHER
+                    ? [`Section`, `Other`]
+                    : [`Section`]; // unrecognised kind — should never happen post-classifier
+            // Compose properties: classifier-supplied properties overlaid on system
+            // fields, system fields winning. For Section:Other, also stamp
+            // classifierReason so the ontology-growth query can surface it.
+            const sectionProps = {
                 ...section.properties,
-                accountId,
-                title: section.title,
-                body: section.body,
-                scope,
-                embedding: bodyEmbedding,
-                createdAt: now,
-                updatedAt: now,
+                ...baseProps,
+                ...(section.kind === SECTION_KIND_OTHER && section.classifierReason
+                    ? { classifierReason: section.classifierReason }
+                    : {}),
+            };
+            const labelClause = sectionLabels.map((l) => `\`${l}\``).join(":");
+            const sectionResult = await dbSession.run(`CREATE (s:${labelClause})
+         SET s = $props
+         WITH s
+         MATCH (d:KnowledgeDocument) WHERE elementId(d) = $docId
+         CREATE (d)-[hs:HAS_SECTION]->(s)
+         SET hs.createdByAgent   = $createdByAgent,
+             hs.createdBySession = $createdBySession,
+             hs.source           = $source,
+             hs.sourceDocumentId = $sourceDocumentId,
+             hs.createdAt        = $createdAt
+         RETURN elementId(s) AS nodeId`, {
+                props: sectionProps,
+                docId: documentNodeId,
                 createdByAgent: PROVENANCE_AGENT,
-                createdBySource: PROVENANCE_AGENT,
                 createdBySession: sessionId ?? "",
                 source: PROVENANCE_SOURCE,
                 sourceDocumentId: attachmentId,
-            };
-            // CREATE the typed node. Label is interpolated (validated against the
-            // ontology label set by the classifier) — Cypher does not allow
-            // parameterising labels.
-            const typedResult = await session.run(`CREATE (t:\`${section.kind}\`)
-         SET t = $props
-         RETURN elementId(t) AS nodeId`, { props: typedProps });
-            const typedNodeId = typedResult.records[0].get("nodeId");
-            // Body overflow → :Chunk children attached directly to the typed node
-            // (mirroring :Section overflow). Most typed nodes won't trip this.
-            if (section.body.length > MAX_CHUNK_SIZE) {
-                const overflowChunks = chunkBody(section.body);
-                const overflowEmbeddings = await embedBatch(overflowChunks);
-                for (let ci = 0; ci < overflowChunks.length; ci++) {
-                    await session.run(`MATCH (t) WHERE elementId(t) = $typedId
-             CREATE (t)-[:HAS_CHUNK]->(c:Chunk {
-               accountId:        $accountId,
-               content:          $content,
-               summary:          $summary,
-               position:         $position,
-               scope:            $scope,
-               embedding:        $embedding,
-               createdAt:        $createdAt,
-               updatedAt:        $updatedAt,
-               createdByAgent:   $createdByAgent,
-               createdBySource:  $createdBySource,
-               createdBySession: $createdBySession,
-               source:           $source,
-               sourceDocumentId: $sourceDocumentId
-             })`, {
-                        typedId: typedNodeId,
-                        accountId,
-                        content: overflowChunks[ci],
-                        summary: overflowChunks[ci].slice(0, PREVIEW_LENGTH),
-                        position: ci,
-                        scope,
-                        embedding: overflowEmbeddings[ci],
-                        createdAt: now,
-                        updatedAt: now,
-                        createdByAgent: PROVENANCE_AGENT,
-                        createdBySource: PROVENANCE_AGENT,
-                        createdBySession: sessionId ?? "",
-                        source: PROVENANCE_SOURCE,
-                        sourceDocumentId: attachmentId,
-                    });
-                    chunkCount += 1;
-                }
-            }
-            // Related nodes (e.g. Position's employer Organization). MERGE when
-            // the related kind has a stable identifying property; CREATE when not.
-            // Provenance is stamped only on creation (ON CREATE SET) so shared
-            // entities don't get rewritten by subsequent ingestions.
-            if (section.related && section.related.length > 0) {
-                for (const related of section.related) {
-                    const relatedNodeId = await writeRelatedNode({
-                        session,
-                        accountId,
-                        related,
-                        now,
-                        sessionId,
-                    });
-                    // Edge from typed node to related node
-                    await session.run(`MATCH (t) WHERE elementId(t) = $typedId
-             MATCH (r) WHERE elementId(r) = $relatedId
-             CREATE (t)-[edge:\`${related.edge.type}\`]->(r)
-             SET edge += $edgeProps`, {
-                        typedId: related.edge.direction === "outgoing" ? typedNodeId : relatedNodeId,
-                        relatedId: related.edge.direction === "outgoing" ? relatedNodeId : typedNodeId,
-                        edgeProps: {
-                            ...(related.edge.properties ?? {}),
-                            createdByAgent: PROVENANCE_AGENT,
-                            createdBySession: sessionId ?? "",
-                            source: PROVENANCE_SOURCE,
-                            sourceDocumentId: attachmentId,
-                            createdAt: now,
-                        },
-                    });
-                }
+                createdAt: now,
+            });
+            const sectionId = sectionResult.records[0].get("nodeId");
+            bumpKind(kindBreakdown, section.kind);
+            bumpEdge(edgeBreakdown, "HAS_SECTION");
+            // 5c. NEXT chain in reading order.
+            if (previousSectionId) {
+                await dbSession.run(`MATCH (a:Section), (b:Section)
+           WHERE elementId(a) = $prev AND elementId(b) = $cur
+           CREATE (a)-[n:NEXT]->(b)
+           SET n.createdByAgent   = $createdByAgent,
+               n.createdBySession = $createdBySession,
+               n.source           = $source,
+               n.sourceDocumentId = $sourceDocumentId,
+               n.createdAt        = $createdAt`, {
+                    prev: previousSectionId,
+                    cur: sectionId,
+                    createdByAgent: PROVENANCE_AGENT,
+                    createdBySession: sessionId ?? "",
+                    source: PROVENANCE_SOURCE,
+                    sourceDocumentId: attachmentId,
+                    createdAt: now,
+                });
+                bumpEdge(edgeBreakdown, "NEXT");
             }
-            // Anchor edge (anchor → typed or typed → anchor)
-            if (section.anchorEdge) {
+            previousSectionId = sectionId;
+            // 5d. Anchor edge (identity kinds only). Writer applies the edge the
+            //     classifier proposed; never invents.
+            if (section.anchorEdge && IDENTITY_KINDS_SET.has(section.kind)) {
                 const direction = section.anchorEdge.direction;
+                const edgeType = section.anchorEdge.type;
                 const edgeProps = {
                     ...(section.anchorEdge.properties ?? {}),
                     createdByAgent: PROVENANCE_AGENT,
@@ -383,59 +317,163 @@ export async function memoryIngest(params) {
                     sourceDocumentId: attachmentId,
                     createdAt: now,
                 };
-                if (direction === "from-anchor") {
-                    await session.run(`MATCH (a:\`${anchorLabel}\`) WHERE elementId(a) = $anchorId AND a.accountId = $accountId
-             MATCH (t) WHERE elementId(t) = $typedId
-             CREATE (a)-[edge:\`${section.anchorEdge.type}\`]->(t)
-             SET edge += $edgeProps`, { anchorId: anchorNodeId, typedId: typedNodeId, accountId, edgeProps });
-                }
-                else {
-                    await session.run(`MATCH (a:\`${anchorLabel}\`) WHERE elementId(a) = $anchorId AND a.accountId = $accountId
-             MATCH (t) WHERE elementId(t) = $typedId
-             CREATE (t)-[edge:\`${section.anchorEdge.type}\`]->(a)
-             SET edge += $edgeProps`, { anchorId: anchorNodeId, typedId: typedNodeId, accountId, edgeProps });
+                const cypher = direction === "from-anchor"
+                    ? `MATCH (a:\`${anchorLabel}\`) WHERE elementId(a) = $anchorId AND a.accountId = $accountId
+             MATCH (s:Section) WHERE elementId(s) = $sectionId
+             CREATE (a)-[edge:\`${edgeType}\`]->(s)
+             SET edge += $edgeProps`
+                    : `MATCH (a:\`${anchorLabel}\`) WHERE elementId(a) = $anchorId AND a.accountId = $accountId
+             MATCH (s:Section) WHERE elementId(s) = $sectionId
+             CREATE (s)-[edge:\`${edgeType}\`]->(a)
+             SET edge += $edgeProps`;
+                await dbSession.run(cypher, { anchorId: anchorNodeId, sectionId, accountId, edgeProps });
+                bumpEdge(edgeBreakdown, edgeType);
+            }
+            // 5e. Related entities (Organization for AT, DefinedTerm for DEFINES on
+            //     :Section:Definitions, etc.). Apply each as the classifier emitted.
+            if (section.related && section.related.length > 0) {
+                for (const related of section.related) {
+                    await writeRelatedAndEdge(dbSession, sectionId, related, accountId, now, sessionId ?? "", attachmentId);
+                    relatedCount += 1;
+                    bumpEdge(edgeBreakdown, related.edge.type);
                 }
             }
-            // (KnowledgeDocument)-[:REFERENCES]->(typed) for retrieval.
-            await session.run(`MATCH (d:KnowledgeDocument) WHERE elementId(d) = $docId
-         MATCH (t) WHERE elementId(t) = $typedId
-         CREATE (d)-[r:REFERENCES]->(t)
-         SET r.createdByAgent   = $createdByAgent,
-             r.createdBySession = $createdBySession,
-             r.source           = $source,
-             r.sourceDocumentId = $sourceDocumentId,
-             r.createdAt        = $createdAt`, {
-                docId: documentNodeId,
-                typedId: typedNodeId,
-                createdByAgent: PROVENANCE_AGENT,
-                createdBySession: sessionId ?? "",
-                source: PROVENANCE_SOURCE,
-                sourceDocumentId: attachmentId,
-                createdAt: now,
-            });
-            entityLinks += 1;
-            typedCount += 1;
-            console.error(`[document-ingest] section kind=${section.kind} title="${section.title}" chars=${section.body.length}`);
         }
-        log("neo4j-done", `doc=${documentNodeId.slice(0, 12)} sections=${sections.length} typed=${typedCount} unmapped=${unmappedCount} chunks=${chunkCount} entityLinks=${entityLinks}`);
-        console.error(`[document-ingest] done sections=${sections.length} typed=${typedCount} unmapped=${unmappedCount} ms=${Date.now() - t0}`);
+        // 6. Document-level edges (PARTY for contracts, etc.). Applied off the
+        //    KnowledgeDocument; classifier proposes, writer applies.
+        if (documentEdges && documentEdges.length > 0) {
+            for (const docEdge of documentEdges) {
+                await writeDocumentEdge(dbSession, documentNodeId, docEdge, accountId, now, sessionId ?? "", attachmentId);
+                relatedCount += 1;
+                bumpEdge(edgeBreakdown, docEdge.type);
+            }
+        }
+        log("neo4j-done", `doc=${documentNodeId.slice(0, 12)} sections=${sections.length} kinds=${JSON.stringify(kindBreakdown)} edges=${JSON.stringify(edgeBreakdown)} related=${relatedCount} orphans=${orphanCandidates.length}`);
+        console.error(`[memory-ingest] sections=${sections.length} chain=${Math.max(0, sections.length - 1)} typed=${formatBreakdown(kindBreakdown)} edges=${formatBreakdown(edgeBreakdown)} orphans=${orphanCandidates.length} docId=${documentNodeId}`);
+        for (const orphan of orphanCandidates) {
+            console.error(`[document-ingest] orphan-candidate node=${orphan.kind} label=${JSON.stringify(orphan.label)} reason=${JSON.stringify(orphan.reason)}`);
+        }
         return {
             documentNodeId,
             sectionCount: sections.length,
-            typedCount,
-            unmappedCount,
-            chunkCount,
-            entityLinks,
+            kindBreakdown,
+            edgeBreakdown,
+            relatedCount,
+            standaloneCount,
+            orphanCandidates,
             documentSummary,
             keywords,
         };
     }
     finally {
         extractCache.delete(attachmentId);
-        await session.close();
+        await dbSession.close();
         log("complete");
     }
 }
+// ---------------------------------------------------------------------------
+// Helpers — standalone-node writer (Project), related-edge writer, document-
+// edge writer.
+// ---------------------------------------------------------------------------
+async function writeStandaloneNode(dbSession, section, baseProps, anchorNodeId, anchorLabel, attachmentId, sessionId, now) {
+    const props = { ...section.properties, ...baseProps };
+    const r = await dbSession.run(`CREATE (n:\`${section.kind}\`)
+     SET n = $props
+     RETURN elementId(n) AS nodeId`, { props });
+    const nodeId = r.records[0].get("nodeId");
+    if (section.anchorEdge) {
+        const direction = section.anchorEdge.direction;
+        const edgeType = section.anchorEdge.type;
+        const edgeProps = {
+            ...(section.anchorEdge.properties ?? {}),
+            createdByAgent: PROVENANCE_AGENT,
+            createdBySession: sessionId,
+            source: PROVENANCE_SOURCE,
+            sourceDocumentId: attachmentId,
+            createdAt: now,
+        };
+        const cypher = direction === "from-anchor"
+            ? `MATCH (a:\`${anchorLabel}\`) WHERE elementId(a) = $anchorId AND a.accountId = $accountId
+         MATCH (n) WHERE elementId(n) = $nodeId
+         CREATE (a)-[edge:\`${edgeType}\`]->(n)
+         SET edge += $edgeProps`
+            : `MATCH (a:\`${anchorLabel}\`) WHERE elementId(a) = $anchorId AND a.accountId = $accountId
+         MATCH (n) WHERE elementId(n) = $nodeId
+         CREATE (n)-[edge:\`${edgeType}\`]->(a)
+         SET edge += $edgeProps`;
+        await dbSession.run(cypher, {
+            anchorId: anchorNodeId,
+            nodeId,
+            accountId: baseProps.accountId,
+            edgeProps,
+        });
+    }
+    return nodeId;
+}
+async function writeRelatedAndEdge(dbSession, fromNodeId, related, accountId, now, sessionId, attachmentId) {
+    const relatedNodeId = await writeRelatedNode({
+        session: dbSession,
+        accountId,
+        related,
+        now,
+        sessionId,
+    });
+    await dbSession.run(`MATCH (a) WHERE elementId(a) = $a
+     MATCH (b) WHERE elementId(b) = $b
+     CREATE (a)-[edge:\`${related.edge.type}\`]->(b)
+     SET edge += $edgeProps`, {
+        a: related.edge.direction === "outgoing" ? fromNodeId : relatedNodeId,
+        b: related.edge.direction === "outgoing" ? relatedNodeId : fromNodeId,
+        edgeProps: {
+            ...(related.edge.properties ?? {}),
+            createdByAgent: PROVENANCE_AGENT,
+            createdBySession: sessionId,
+            source: PROVENANCE_SOURCE,
+            sourceDocumentId: attachmentId,
+            createdAt: now,
+        },
+    });
+}
+async function writeDocumentEdge(dbSession, documentNodeId, docEdge, accountId, now, sessionId, attachmentId) {
+    // Build a synthetic ClassifiedRelated so we can reuse writeRelatedNode for
+    // the target. The MERGE-vs-CREATE decision is the same; the edge is off
+    // the KnowledgeDocument rather than off a Section.
+    const synthetic = {
+        kind: docEdge.targetKind,
+        properties: docEdge.targetProperties,
+        edge: { type: docEdge.type, direction: docEdge.direction },
+        merge: docEdge.merge !== false,
+    };
+    const targetNodeId = await writeRelatedNode({
+        session: dbSession,
+        accountId,
+        related: synthetic,
+        now,
+        sessionId,
+    });
+    await dbSession.run(`MATCH (d:KnowledgeDocument) WHERE elementId(d) = $docId
+     MATCH (n) WHERE elementId(n) = $targetId
+     CREATE (d)-[edge:\`${docEdge.type}\`]->(n)
+     SET edge.createdByAgent   = $createdByAgent,
+         edge.createdBySession = $createdBySession,
+         edge.source           = $source,
+         edge.sourceDocumentId = $sourceDocumentId,
+         edge.createdAt        = $createdAt`, {
+        docId: documentNodeId,
+        targetId: targetNodeId,
+        createdByAgent: PROVENANCE_AGENT,
+        createdBySession: sessionId,
+        source: PROVENANCE_SOURCE,
+        sourceDocumentId: attachmentId,
+        createdAt: now,
+    });
+}
+function formatBreakdown(b) {
+    const entries = Object.entries(b);
+    if (entries.length === 0)
+        return "{}";
+    return entries.map(([k, v]) => `${k}:${v}`).join(",");
+}
 async function writeRelatedNode(opts) {
     const { session, accountId, related, now, sessionId } = opts;
     // Compute embedding from a representative property string so the related