@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,827 @@
+import { getSession } from "../lib/neo4j.js";
+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";
+import { isConversationSource } from "../lib/conversation-normalisers/types.js";
+// ---------------------------------------------------------------------------
+// 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    Section nodes
+//                      (idempotent)         Section/Chunk/typed  Ollama   + secondary labels
+//                                                                         + NEXT chain
+//                                                                         + anchor edges
+//                                                                         + related entities
+//                                                                         + KD-level edges
+//
+// 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 so re-ingest cleanup finds
+// them deterministically.
+// ---------------------------------------------------------------------------
+const PREVIEW_LENGTH = 150;
+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
+// ---------------------------------------------------------------------------
+function normaliseKeywords(arr) {
+    if (!arr || arr.length === 0)
+        return [];
+    return arr.map((k) => k.toLowerCase().trim()).filter(Boolean);
+}
+/**
+ * Identifying property for MERGE on a related node by kind.
+ * Choose a stable, human-recognisable key per label so the same real-world
+ * entity collapses to one node across documents.
+ */
+function mergeKeyFor(kind, properties) {
+    switch (kind) {
+        case "Organization":
+            return typeof properties.name === "string" && properties.name.trim()
+                ? { key: "name", value: properties.name.trim() }
+                : null;
+        case "Person":
+            if (typeof properties.email === "string" && properties.email.trim()) {
+                return { key: "email", value: properties.email.trim() };
+            }
+            if (typeof properties.telephone === "string" && properties.telephone.trim()) {
+                return { key: "telephone", value: properties.telephone.trim() };
+            }
+            return null;
+        case "DefinedTerm":
+            return typeof properties.name === "string" && properties.name.trim()
+                ? { key: "name", value: properties.name.trim() }
+                : null;
+        case "Credential":
+            return typeof properties.name === "string" && properties.name.trim()
+                ? { key: "name", value: properties.name.trim() }
+                : null;
+        default:
+            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) {
+    // Task 891 — ConversationArchive branch. Diverges enough from the document
+    // path (no extract cache, no anchor edges, no related entities, delta-append
+    // semantics) that it has its own end-to-end implementation in
+    // ingestConversationArchive(). The brief consolidates these as one entry
+    // (`memoryIngest` with `parentLabel`) so callers see one tool.
+    if (params.parentLabel === "ConversationArchive") {
+        return ingestConversationArchive(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}'");
+    }
+    if (!anchorNodeId) {
+        throw new Error("anchorNodeId is required — the document subject's element ID (UserProfile/LocalBusiness/Person/Organization)");
+    }
+    if (!anchorLabel) {
+        throw new Error("anchorLabel is required — the anchor node's primary label");
+    }
+    const keywords = (() => {
+        const u = normaliseKeywords(rawUserKeywords);
+        const d = normaliseKeywords(rawDocKeywords);
+        if (u.length === 0 && d.length === 0)
+            return undefined;
+        return [...new Set([...u, ...d])];
+    })();
+    const t0 = Date.now();
+    const log = (stage, detail) => console.error(`[memory-ingest] [${attachmentId.slice(0, 8)}] ${stage}${detail ? ` — ${detail}` : ""} (${Date.now() - t0}ms)`);
+    log("start", `${sections.length} sections, scope=${scope}, anchor=${anchorLabel}`);
+    const cached = extractCache.get(attachmentId);
+    if (!cached) {
+        throw new Error(`No cached extract found for attachment "${attachmentId}". ` +
+            `Call memory-ingest-extract first.`);
+    }
+    log("cache-hit", cached.filename);
+    const { filename, mimeType } = cached;
+    const now = new Date().toISOString();
+    // 1. Embed document summary + every section body in one batch.
+    const textsToEmbed = [documentSummary, ...sections.map((s) => s.body)];
+    log("embedding", `${textsToEmbed.length} texts`);
+    const embeddings = await embedBatch(textsToEmbed);
+    log("embedded", `${embeddings.length} vectors`);
+    const docEmbedding = embeddings[0];
+    const dbSession = getSession();
+    let documentNodeId = "";
+    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 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: dbSession, accountId, elementId: eid });
+            log("revived", `restored trashed KnowledgeDocument elementId=${eid}`);
+        }
+        // 3. MERGE the KnowledgeDocument parent. Optional fields (sourceUrl,
+        //    sourceType, keywords) are SET only when present so re-ingest of a
+        //    file upload doesn't null out a previously-set web-source URL.
+        const optionalSets = [];
+        const optionalParams = {};
+        if (sourceUrl !== undefined) {
+            optionalSets.push("d.sourceUrl = $sourceUrl");
+            optionalParams.sourceUrl = sourceUrl;
+        }
+        if (sourceType !== undefined) {
+            optionalSets.push("d.sourceType = $sourceType");
+            optionalParams.sourceType = sourceType;
+        }
+        if (keywords !== undefined) {
+            optionalSets.push("d.keywords = $keywords");
+            optionalParams.keywords = keywords;
+        }
+        const optionalSetClause = optionalSets.length > 0 ? ", " + optionalSets.join(", ") : "";
+        const docResult = await dbSession.run(`MERGE (d:KnowledgeDocument { attachmentId: $attachmentId })
+       SET d.accountId      = $accountId,
+           d.name           = $filename,
+           d.encodingFormat = $mimeType,
+           d.summary        = $documentSummary,
+           d.sectionCount   = $sectionCount,
+           d.scope          = $scope,
+           d.embedding      = $embedding,
+           d.createdAt      = coalesce(d.createdAt, $createdAt),
+           d.updatedAt      = $updatedAt
+           ${optionalSetClause}
+       REMOVE d.deletedAt
+       RETURN elementId(d) AS nodeId`, {
+            attachmentId,
+            accountId,
+            filename,
+            mimeType,
+            documentSummary,
+            sectionCount: sections.length,
+            scope,
+            embedding: docEmbedding,
+            createdAt: now,
+            updatedAt: now,
+            ...optionalParams,
+        });
+        documentNodeId = docResult.records[0].get("nodeId");
+        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. 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 baseProps = {
+                accountId,
+                title: section.title,
+                body: section.body,
+                bodyPreview: section.body.slice(0, PREVIEW_LENGTH),
+                position: i,
+                scope,
+                embedding: bodyEmbedding,
+                createdAt: now,
+                updatedAt: now,
+                createdByAgent: PROVENANCE_AGENT,
+                createdBySource: PROVENANCE_AGENT,
+                createdBySession: sessionId ?? "",
+                source: PROVENANCE_SOURCE,
+                sourceDocumentId: attachmentId,
+            };
+            // 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);
+                    }
+                }
+                continue;
+            }
+            // 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,
+                ...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,
+                createdBySession: sessionId ?? "",
+                source: PROVENANCE_SOURCE,
+                sourceDocumentId: attachmentId,
+                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");
+            }
+            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,
+                    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 (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);
+                }
+            }
+        }
+        // 6. Document-level edges (PARTY for contracts, PARTICIPANT for meetings/calls,
+        //    FROM/TO/CC for emails, SPEAKER for voice-notes). Applied off the
+        //    KnowledgeDocument; classifier proposes, writer applies.
+        if (documentEdges && documentEdges.length > 0) {
+            const docEdgeTypes = Array.from(new Set(documentEdges.map((e) => e.type))).sort().join(",");
+            console.error(`[memory-ingest] documentEdges count=${documentEdges.length} types=${docEdgeTypes}`);
+            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,
+            kindBreakdown,
+            edgeBreakdown,
+            relatedCount,
+            standaloneCount,
+            orphanCandidates,
+            documentSummary,
+            keywords,
+        };
+    }
+    finally {
+        extractCache.delete(attachmentId);
+        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
+    // node is searchable. Falls back to label+JSON if no `name` field exists.
+    const embedSource = typeof related.properties.name === "string"
+        ? related.properties.name
+        : `${related.kind} ${JSON.stringify(related.properties)}`;
+    const relatedEmbedding = await embed(embedSource);
+    const mergeKey = related.merge !== false ? mergeKeyFor(related.kind, related.properties) : null;
+    if (mergeKey) {
+        // MERGE on the identifying property + accountId. ON CREATE stamps
+        // provenance; ON MATCH leaves provenance intact (so re-ingest of the
+        // same Organization across docs doesn't overwrite the original
+        // provenance — first-write wins for shared entities).
+        const result = await session.run(`MERGE (r:\`${related.kind}\` { accountId: $accountId, \`${mergeKey.key}\`: $mergeValue })
+       ON CREATE SET r += $createProps,
+                     r.embedding        = $embedding,
+                     r.createdAt        = $createdAt,
+                     r.updatedAt        = $createdAt,
+                     r.createdByAgent   = $createdByAgent,
+                     r.createdBySource  = $createdByAgent,
+                     r.createdBySession = $createdBySession,
+                     r.source           = $source
+       ON MATCH  SET r.updatedAt = $createdAt
+       RETURN elementId(r) AS nodeId`, {
+            accountId,
+            mergeValue: mergeKey.value,
+            createProps: { ...related.properties, accountId, scope: "shared" },
+            embedding: relatedEmbedding,
+            createdAt: now,
+            createdByAgent: PROVENANCE_AGENT,
+            createdBySession: sessionId ?? "",
+            source: PROVENANCE_SOURCE,
+        });
+        return result.records[0].get("nodeId");
+    }
+    // CREATE — no stable identifying property, treat as one-of-a-kind for
+    // this document. Track sourceDocumentId so re-ingest cleanup catches it.
+    const result = await session.run(`CREATE (r:\`${related.kind}\`)
+     SET r = $props
+     RETURN elementId(r) AS nodeId`, {
+        props: {
+            ...related.properties,
+            accountId,
+            scope: "shared",
+            embedding: relatedEmbedding,
+            createdAt: now,
+            updatedAt: now,
+            createdByAgent: PROVENANCE_AGENT,
+            createdBySource: PROVENANCE_AGENT,
+            createdBySession: sessionId ?? "",
+            source: PROVENANCE_SOURCE,
+        },
+    });
+    return result.records[0].get("nodeId");
+}
+// ---------------------------------------------------------------------------
+// ConversationArchive ingest (Task 891) — chat-mode branch.
+//
+// MERGE :ConversationArchive on conversationIdentity → cleanup THIS export's
+// chunks by archiveSha256 (delta discipline: prior exports' chunks survive)
+// → CREATE new chunks → extend NEXT chain from existing tail → MERGE
+// :PARTICIPANT_IN edges → update lastIngestedMessageHash + lastIngestedMessageAt.
+//
+// No anchor edges, no related entities, no documentEdges, no orphan candidates.
+// Sections in this branch are :Section:Conversation chunks; properties pass
+// through verbatim (summary, keywords, firstMessageAt, lastMessageAt,
+// participantNames, messageCount).
+// ---------------------------------------------------------------------------
+// Source-agnostic provenance (Task 894). The orchestrator is one bash entry
+// regardless of source, so the agent stamp is the same across every ingest;
+// the source format flows into `source` instead.
+const CHAT_PROVENANCE_AGENT = "conversation-archive";
+async function ingestConversationArchive(params) {
+    const { accountId, attachmentId: conversationIdentity, // semantic rename per parentLabel
+    documentSummary, sections, scope, documentKeywords: rawDocKeywords, userKeywords: rawUserKeywords, sessionId, archiveSha256, archiveSourceFile, lastIngestedMessageHash, lastIngestedMessageAt, participantElementIds = [], source, 
+    // Task 902 sub-scope B — default `false` is the non-destructive contract.
+    // The Task 894 bin previously defaulted this to `true` (cleanup-on-every-
+    // run-by-archiveSha256), which combined with `--session-gap-hours` to
+    // silently destroy 138 chunks during the Adam Mackay re-gap. Default
+    // `false` means cleanup never fires unless the caller explicitly opts in;
+    // the bin only opts in under `--rebuild` AND on the first session.
+    cleanupPriorChunks = false, archiveTitle, } = params;
+    if (!scope) {
+        throw new Error("scope is required");
+    }
+    if (!source || !isConversationSource(source)) {
+        throw new Error(`source is required for parentLabel='ConversationArchive' and must be one of the closed enum (got ${JSON.stringify(source)}).`);
+    }
+    if (!archiveSha256 || !archiveSha256.trim()) {
+        throw new Error("archiveSha256 is required for parentLabel='ConversationArchive'");
+    }
+    if (!archiveSourceFile || !archiveSourceFile.trim()) {
+        throw new Error("archiveSourceFile is required for parentLabel='ConversationArchive'");
+    }
+    if (!lastIngestedMessageHash || !lastIngestedMessageHash.trim()) {
+        throw new Error("lastIngestedMessageHash is required for parentLabel='ConversationArchive'");
+    }
+    if (!lastIngestedMessageAt || !lastIngestedMessageAt.trim()) {
+        throw new Error("lastIngestedMessageAt is required for parentLabel='ConversationArchive'");
+    }
+    const keywords = (() => {
+        const u = (rawUserKeywords ?? []).map((k) => k.toLowerCase().trim()).filter(Boolean);
+        const d = (rawDocKeywords ?? []).map((k) => k.toLowerCase().trim()).filter(Boolean);
+        if (u.length === 0 && d.length === 0)
+            return undefined;
+        return [...new Set([...u, ...d])];
+    })();
+    const t0 = Date.now();
+    const log = (stage, detail) => console.error(`[memory-ingest] [CA:${conversationIdentity.slice(0, 8)}] ${stage}${detail ? ` — ${detail}` : ""} (${Date.now() - t0}ms)`);
+    log("start", `${sections.length} chunks, archiveSha256=${archiveSha256.slice(0, 12)}, scope=${scope}`);
+    const now = new Date().toISOString();
+    const dbSession = getSession();
+    let archiveNodeId = "";
+    const kindBreakdown = {};
+    const edgeBreakdown = {};
+    try {
+        // 1. Trash-revival — mirror of the KnowledgeDocument path above (Task 576).
+        //    `:ConversationArchive` is NOT in graph-trash's UNIQUE_KEYS_BY_LABEL,
+        //    so trashing leaves `conversationIdentity` populated; the lookup is by
+        //    property directly rather than `_trashedKeys CONTAINS`. Without this,
+        //    re-ingesting into a previously-trashed archive (operator manually
+        //    drag-trashed, then re-ran) MERGEs into the trashed node, writes
+        //    chunks under a `:Trashed` parent, and the graph UI hides the whole
+        //    chain — the chunks land but are invisible until something else
+        //    clears the label.
+        const trashedArchive = await dbSession.run(`MATCH (a:ConversationArchive:Trashed)
+       WHERE a.accountId = $accountId
+         AND a.conversationIdentity = $conversationIdentity
+       RETURN elementId(a) AS eid LIMIT 1`, { accountId, conversationIdentity });
+        if (trashedArchive.records.length > 0) {
+            const eid = trashedArchive.records[0].get("eid");
+            await restoreNode({ session: dbSession, accountId, elementId: eid });
+            log("revived", `restored trashed ConversationArchive elementId=${eid}`);
+        }
+        // 2. Embed every chunk body. Summary too (parent embedding).
+        const textsToEmbed = [documentSummary, ...sections.map((s) => s.body)];
+        log("embedding", `${textsToEmbed.length} texts`);
+        const embeddings = await embedBatch(textsToEmbed);
+        const archiveEmbedding = embeddings[0];
+        // 3. MERGE :ConversationArchive on conversationIdentity. ON CREATE stamps
+        //    immutable identity props; ON MATCH bumps the cursor + last-ingest
+        //    timestamps so the next delta-append run finds the right point.
+        //
+        //    Task 902 sub-scope A — `a.title` is the stable label for the parent.
+        //    ON CREATE sets it; ON MATCH uses COALESCE so an existing title is
+        //    NEVER overwritten (re-ingests must produce the same title anyway,
+        //    but the COALESCE makes the contract explicit). UI prefers `title`
+        //    via display-helpers' :ConversationArchive branch.
+        const archiveResult = await dbSession.run(`MERGE (a:ConversationArchive { conversationIdentity: $conversationIdentity })
+       ON CREATE SET a.accountId               = $accountId,
+                     a.scope                   = $scope,
+                     a.title                   = $archiveTitle,
+                     a.summary                 = $documentSummary,
+                     a.keywords                = $keywords,
+                     a.embedding               = $archiveEmbedding,
+                     a.archiveSourceFile       = $archiveSourceFile,
+                     a.createdAt               = $createdAt,
+                     a.createdBySession        = $sessionId,
+                     a.createdByAgent          = $createdByAgent,
+                     a.source                  = $source
+       SET a.updatedAt                = $updatedAt,
+           a.title                    = COALESCE(a.title, $archiveTitle),
+           a.lastIngestedMessageHash  = $lastIngestedMessageHash,
+           a.lastIngestedMessageAt    = $lastIngestedMessageAt,
+           a.lastIngestedBySession    = $sessionId,
+           a.lastIngestedArchiveSha256 = $archiveSha256
+       RETURN elementId(a) AS nodeId, count(a) AS affected`, {
+            conversationIdentity,
+            accountId,
+            scope,
+            archiveTitle: archiveTitle ?? null,
+            documentSummary,
+            keywords: keywords ?? [],
+            archiveEmbedding,
+            archiveSourceFile,
+            createdAt: now,
+            updatedAt: now,
+            sessionId: sessionId ?? "",
+            createdByAgent: CHAT_PROVENANCE_AGENT,
+            source: source,
+            lastIngestedMessageHash,
+            lastIngestedMessageAt,
+            archiveSha256,
+        });
+        if (archiveResult.records[0]?.get("affected")?.toNumber?.() !== 1) {
+            throw new Error("memory-ingest: ConversationArchive MERGE returned no row — Cypher silent no-op");
+        }
+        archiveNodeId = archiveResult.records[0].get("nodeId");
+        log("archive-merged", `nodeId=${archiveNodeId.slice(0, 12)}`);
+        // 4. Cleanup chunks of THIS export (idempotency for re-running the same
+        //    export bytes). Delta-append re-imports of NEWER exports leave prior
+        //    chunks alone because their archiveSha256 differs. Task 900 sub-scope
+        //    E: skipped on per-session calls after the first, or this would
+        //    delete the chunks that earlier sessions in the same run just wrote
+        //    (matching conversationIdentity + matching archiveSha256).
+        let cleanedPriorChunks = 0;
+        if (cleanupPriorChunks) {
+            const cleanup = await dbSession.run(`MATCH (a:ConversationArchive { conversationIdentity: $conversationIdentity })
+               -[hs:HAS_SECTION]->(c:Section:Conversation { archiveSha256: $archiveSha256 })
+         DETACH DELETE c
+         RETURN count(c) AS removed`, { conversationIdentity, archiveSha256 });
+            cleanedPriorChunks = cleanup.records[0]?.get("removed")?.toNumber?.() ?? 0;
+            if (cleanedPriorChunks > 0) {
+                log("cleanup", `dropped ${cleanedPriorChunks} prior chunks for this archiveSha256`);
+            }
+        }
+        else {
+            log("cleanup-skipped", `cleanupPriorChunks=false (default non-destructive contract — only --rebuild's first session sets true)`);
+        }
+        // 5. Find existing tail of NEXT chain (if any). Delta-append wires the
+        //    new first chunk after this tail; first-ever ingest finds nothing.
+        const tailResult = await dbSession.run(`MATCH (a:ConversationArchive { conversationIdentity: $conversationIdentity })
+             -[:HAS_SECTION]->(c:Section:Conversation)
+       WHERE NOT (c)-[:NEXT]->(:Section:Conversation)
+       RETURN elementId(c) AS tailId LIMIT 1`, { conversationIdentity });
+        let previousChunkId = tailResult.records[0]?.get("tailId") ?? null;
+        if (previousChunkId) {
+            log("tail-found", `extending NEXT chain from elementId=${previousChunkId.slice(0, 12)}`);
+        }
+        // 6. CREATE chunk nodes + HAS_SECTION + NEXT chain.
+        let chunksWritten = 0;
+        let nextEdgesCreated = 0;
+        for (let i = 0; i < sections.length; i++) {
+            const section = sections[i];
+            const bodyEmbedding = embeddings[i + 1];
+            const baseProps = {
+                accountId,
+                title: section.title,
+                body: section.body,
+                bodyPreview: section.body.slice(0, PREVIEW_LENGTH),
+                position: i,
+                scope,
+                embedding: bodyEmbedding,
+                createdAt: now,
+                updatedAt: now,
+                createdByAgent: CHAT_PROVENANCE_AGENT,
+                createdBySource: CHAT_PROVENANCE_AGENT,
+                createdBySession: sessionId ?? "",
+                source: source,
+                archiveSha256,
+                archiveSourceFile,
+            };
+            const chunkProps = { ...section.properties, ...baseProps };
+            const r = await dbSession.run(`CREATE (c:Section:Conversation)
+         SET c = $props
+         WITH c
+         MATCH (a:ConversationArchive { conversationIdentity: $conversationIdentity })
+         CREATE (a)-[hs:HAS_SECTION]->(c)
+         SET hs.createdByAgent   = $createdByAgent,
+             hs.createdBySession = $createdBySession,
+             hs.source           = $source,
+             hs.archiveSha256    = $archiveSha256,
+             hs.createdAt        = $createdAt
+         RETURN elementId(c) AS nodeId`, {
+                props: chunkProps,
+                conversationIdentity,
+                createdByAgent: CHAT_PROVENANCE_AGENT,
+                createdBySession: sessionId ?? "",
+                source: source,
+                archiveSha256,
+                createdAt: now,
+            });
+            const chunkId = r.records[0].get("nodeId");
+            chunksWritten++;
+            bumpKind(kindBreakdown, "Conversation");
+            bumpEdge(edgeBreakdown, "HAS_SECTION");
+            if (previousChunkId) {
+                const nextRes = await dbSession.run(`MATCH (prev:Section:Conversation), (cur:Section:Conversation)
+           WHERE elementId(prev) = $prev AND elementId(cur) = $cur
+           CREATE (prev)-[n:NEXT]->(cur)
+           SET n.createdByAgent   = $createdByAgent,
+               n.createdBySession = $createdBySession,
+               n.source           = $source,
+               n.archiveSha256    = $archiveSha256,
+               n.createdAt        = $createdAt
+           RETURN count(n) AS created`, {
+                    prev: previousChunkId,
+                    cur: chunkId,
+                    createdByAgent: CHAT_PROVENANCE_AGENT,
+                    createdBySession: sessionId ?? "",
+                    source: source,
+                    archiveSha256,
+                    createdAt: now,
+                });
+                if (nextRes.records[0]?.get("created")?.toNumber?.() !== 1) {
+                    throw new Error("memory-ingest: NEXT edge CREATE returned no row — silent no-op");
+                }
+                nextEdgesCreated++;
+                bumpEdge(edgeBreakdown, "NEXT");
+            }
+            previousChunkId = chunkId;
+        }
+        // 7. MERGE :PARTICIPANT_IN edges from each operator-confirmed participant
+        //    to the archive. Idempotent — re-runs are no-ops on the edge set.
+        let participantEdgesMerged = 0;
+        for (const elemId of participantElementIds) {
+            const pres = await dbSession.run(`MATCH (a:ConversationArchive { conversationIdentity: $conversationIdentity })
+         MATCH (p) WHERE elementId(p) = $elemId AND (p:Person OR p:AdminUser)
+         MERGE (p)-[r:PARTICIPANT_IN]->(a)
+         ON CREATE SET r.createdByAgent   = $createdByAgent,
+                       r.createdBySession = $createdBySession,
+                       r.source           = $source,
+                       r.createdAt        = $createdAt
+         RETURN count(r) AS merged`, {
+                conversationIdentity,
+                elemId,
+                createdByAgent: CHAT_PROVENANCE_AGENT,
+                createdBySession: sessionId ?? "",
+                source: source,
+                createdAt: now,
+            });
+            const merged = pres.records[0]?.get("merged")?.toNumber?.() ?? 0;
+            if (merged !== 1) {
+                throw new Error(`memory-ingest: PARTICIPANT_IN MERGE for elementId=${elemId} returned no row — Person/AdminUser may not exist or label mismatch`);
+            }
+            participantEdgesMerged++;
+            bumpEdge(edgeBreakdown, "PARTICIPANT_IN");
+        }
+        log("neo4j-done", `archive=${archiveNodeId.slice(0, 12)} chunks=${chunksWritten} next-edges=${nextEdgesCreated} participants=${participantEdgesMerged}`);
+        return {
+            documentNodeId: archiveNodeId,
+            sectionCount: chunksWritten,
+            kindBreakdown,
+            edgeBreakdown,
+            relatedCount: 0,
+            standaloneCount: 0,
+            orphanCandidates: [],
+            documentSummary,
+            keywords,
+            cleanedPriorChunks,
+        };
+    }
+    finally {
+        await dbSession.close();
+        log("complete");
+    }
+}
+//# sourceMappingURL=memory-ingest.js.map