@rubytech/create-maxy 1.0.693 → 1.0.694

package/payload/platform/lib/graph-search/src/index.ts

@@ -0,0 +1,498 @@
+/**
+ * Shared hybrid search primitive over the Neo4j knowledge graph.
+ *
+ * Pre-Task-675 there were two BM25 implementations over the same
+ * `knowledge_fulltext` index — one in the memory MCP tool, one in the admin
+ * Hono route — with divergent filter semantics (soft-delete primitive) and
+ * divergent ranking (agent ran hybrid vector+BM25, UI ran BM25-only). Task
+ * 675 collapses both into this lib; memory MCP + admin route now share
+ * a single code path so `/graph` UI ranking matches what the agent sees.
+ *
+ *   QUERY -->  EMBED -->  VECTOR SEARCH (per index) --> ┐
+ *        │                                               ├--> MERGE --> EXPAND --> RESULTS
+ *        └-->  BM25 FULL-TEXT SEARCH -------------------> ┘
+ *
+ * Hybrid merge: normalise BM25 scores to [0,1] via min-max, then combine
+ *   combined = 0.7 * vector_score + 0.3 * normalised_bm25_score
+ * Dedup by nodeId, keeping the higher combined score.
+ *
+ * Trashed nodes (`:Trashed` label + legacy `deletedAt` property) are
+ * excluded from every path via `notTrashed()` from `graph-trash`.
+ *
+ * The lib is STATELESS. Callers pass a `Session` and, for hybrid, an
+ * `embed` function. This keeps the lib independent of Ollama config and
+ * free of circular imports against each caller's own getSession/embed
+ * (memory MCP and the Hono ui build each have their own copies for
+ * cross-build-boundary reasons — see neo4j-store.ts:68 comment).
+ *
+ * Log emission is the caller's responsibility — the lib throws or returns
+ * `mode` in the result so the caller can format its own `[graph-search]`
+ * line with the prefix and fields it wants.
+ */
+
+import { int, type Session } from "neo4j-driver";
+import { notTrashed } from "../../graph-trash/dist/index.js";
+
+const VECTOR_WEIGHT = 0.7;
+const BM25_WEIGHT = 0.3;
+const FULLTEXT_INDEX_NAME = "knowledge_fulltext";
+
+export interface SearchHit {
+  nodeId: string;
+  labels: string[];
+  properties: Record<string, unknown>;
+  score: number;
+}
+
+export interface SearchResult extends SearchHit {
+  related: Array<{
+    relationship: string;
+    direction: string;
+    labels: string[];
+    properties: Record<string, unknown>;
+  }>;
+}
+
+export interface ScoredNode {
+  nodeId: string;
+  labels: string[];
+  properties: Record<string, unknown>;
+  vectorScore: number;
+  bm25Score: number;
+}
+
+export type SearchMode = "hybrid" | "bm25";
+
+export interface Bm25OnlyParams {
+  query: string;
+  accountId?: string;
+  limit: number;
+  allowedScopes?: string[];
+  agentSlug?: string;
+  keywords?: string[];
+  keywordMatch?: "any" | "all";
+}
+
+export interface HybridParams extends Bm25OnlyParams {
+  labels?: string[];
+  expandHops?: number;
+  keywordSubscriptions?: string[];
+  /**
+   * When true, a failing `embed()` does NOT throw — the lib falls back to
+   * `bm25Only()` and returns `mode: "bm25"`. Admin-route callers set this
+   * true so Ollama-down degrades to BM25-only; MCP tool callers leave it
+   * false so embed failure surfaces loudly.
+   */
+  degradeOnEmbedFailure?: boolean;
+}
+
+export interface HybridResponse {
+  mode: SearchMode;
+  results: SearchResult[];
+  /** Populated when degradeOnEmbedFailure fired. Caller logs it. */
+  embedError?: string;
+}
+
+export type EmbedFn = (text: string) => Promise<number[]>;
+
+/**
+ * Lucene-escape special characters per Neo4j's fulltext query grammar.
+ * `/[+\-&|!(){}[\]^"~*?:\\/]/g` — matches memory-search.ts:127 and
+ * neo4j-store.ts:2521 verbatim; consolidation preserves escape set.
+ */
+export function escapeLucene(query: string): string {
+  return query.replace(/[+\-&|!(){}[\]^"~*?:\\/]/g, "\\$&");
+}
+
+/**
+ * Normalise BM25 scores to [0, 1] using min-max within the result set.
+ * If all scores are equal (or single result), returns 1.0 for all —
+ * the range-zero branch prevents divide-by-zero and keeps the combined
+ * score meaningful.
+ */
+export function normaliseBm25Scores(scores: number[]): number[] {
+  if (scores.length === 0) return [];
+  const min = Math.min(...scores);
+  const max = Math.max(...scores);
+  const range = max - min;
+  if (range === 0) return scores.map(() => 1.0);
+  return scores.map((s) => (s - min) / range);
+}
+
+// Module-scope vector-index cache — discovered from Neo4j at first query.
+// Per-process singleton matches memory-search.ts behaviour.
+let indexCache: Map<string, string> | null = null;
+
+export async function discoverIndexes(session: Session): Promise<Map<string, string>> {
+  if (indexCache) return indexCache;
+  const result = await session.run(
+    `SHOW INDEXES YIELD name, labelsOrTypes, type WHERE type = 'VECTOR' RETURN name, labelsOrTypes`
+  );
+  const fresh = new Map<string, string>();
+  for (const record of result.records) {
+    const name = record.get("name") as string;
+    const labels = record.get("labelsOrTypes") as string[];
+    for (const label of labels) fresh.set(label, name);
+  }
+  indexCache = fresh;
+  return fresh;
+}
+
+/** Clear the index cache — call after schema changes. */
+export function clearIndexCache(): void {
+  indexCache = null;
+}
+
+interface KeywordFilter {
+  clause: string;
+  params: Record<string, unknown>;
+}
+
+function buildKeywordFilter(
+  keywords: string[] | undefined,
+  keywordMatch: "any" | "all" = "any",
+): KeywordFilter | undefined {
+  if (!keywords || keywords.length === 0) return undefined;
+  const fn = keywordMatch === "all" ? "ALL" : "ANY";
+  return {
+    clause: `AND (node.keywords IS NULL OR ${fn}(kw IN $keywords WHERE kw IN node.keywords))`,
+    params: { keywords: keywords.map((k) => k.toLowerCase().trim()) },
+  };
+}
+
+/**
+ * BM25 full-text search against the `knowledge_fulltext` index.
+ * Returns [] when the index doesn't exist — matches memory-search.ts
+ * graceful-fallback semantics so a fresh account with no documents
+ * doesn't 500 the caller.
+ */
+export async function bm25Only(
+  session: Session,
+  params: Bm25OnlyParams,
+): Promise<SearchHit[]> {
+  const { query, accountId, limit, allowedScopes, agentSlug, keywords, keywordMatch } = params;
+  const scopeClause = allowedScopes
+    ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
+    : "";
+  const agentClause = agentSlug
+    ? "AND node.agents IS NOT NULL AND $agentSlug IN node.agents"
+    : "";
+  const keywordFilter = buildKeywordFilter(keywords, keywordMatch);
+  const kwClause = keywordFilter?.clause ?? "";
+  const escaped = escapeLucene(query);
+
+  try {
+    const result = await session.run(
+      `CALL db.index.fulltext.queryNodes($indexName, $query)
+       YIELD node, score
+       WHERE node.accountId = $accountId
+       ${scopeClause}
+       ${agentClause}
+       AND ${notTrashed("node")}
+       ${kwClause}
+       RETURN node, score, labels(node) AS nodeLabels, elementId(node) AS nodeId
+       ORDER BY score DESC
+       LIMIT $limit`,
+      {
+        indexName: FULLTEXT_INDEX_NAME,
+        query: escaped,
+        accountId,
+        limit: int(limit),
+        ...(allowedScopes ? { allowedScopes } : {}),
+        ...(agentSlug ? { agentSlug } : {}),
+        ...(keywordFilter?.params ?? {}),
+      },
+    );
+    return result.records.map((r) => {
+      const scoreRaw = r.get("score");
+      const score = typeof scoreRaw === "number" ? scoreRaw : Number(scoreRaw);
+      const node = r.get("node") as { properties: Record<string, unknown> };
+      return {
+        nodeId: r.get("nodeId") as string,
+        labels: r.get("nodeLabels") as string[],
+        properties: plainProperties(node.properties),
+        score,
+      };
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("index") || msg.includes("fulltext") || msg.includes("not found")) {
+      return [];
+    }
+    throw err;
+  }
+}
+
+/**
+ * Hybrid vector + BM25 search with graph expansion.
+ *
+ * Sequence:
+ *  1. embed(query) — may throw if Ollama is unreachable. When
+ *     `degradeOnEmbedFailure=true`, caller receives bm25Only() result
+ *     with `mode: "bm25"`; otherwise the throw propagates.
+ *  2. Vector search per label (one query per vector index discovered at
+ *     boot). Nodes-by-label filter short-circuits when the requested
+ *     labels have no index.
+ *  3. BM25 search on knowledge_fulltext — same filter semantics as
+ *     vector half (scope/agent/keyword/trashed).
+ *  4. Keyword subscriptions (when set): BM25 per keyword + property
+ *     lookup against `node.keywords` array. Both bypass the agentSlug
+ *     filter — subscriptions are scope-inclusive by design (matches
+ *     memory-search.ts comment L319).
+ *  5. Merge: 0.7*vector + 0.3*bm25_norm, dedup by nodeId, sort.
+ *  6. Graph expand (1 hop by default, 0 to skip) — notTrashed filter +
+ *     scope + agent clauses mirrored.
+ */
+export async function hybrid(
+  session: Session,
+  embed: EmbedFn,
+  params: HybridParams,
+): Promise<HybridResponse> {
+  const {
+    query,
+    labels,
+    accountId,
+    limit,
+    allowedScopes,
+    keywords,
+    keywordMatch = "any",
+    agentSlug,
+    keywordSubscriptions,
+    expandHops = 1,
+    degradeOnEmbedFailure = false,
+  } = params;
+
+  let queryEmbedding: number[];
+  try {
+    queryEmbedding = await embed(query);
+  } catch (err) {
+    if (!degradeOnEmbedFailure) throw err;
+    const msg = err instanceof Error ? err.message : String(err);
+    const bm25Hits = await bm25Only(session, params);
+    const results: SearchResult[] = bm25Hits.map((h) => ({ ...h, related: [] }));
+    return { mode: "bm25", results, embedError: msg };
+  }
+
+  const labelToIndex = await discoverIndexes(session);
+
+  const keywordFilter = buildKeywordFilter(keywords, keywordMatch);
+  const keywordClause = keywordFilter?.clause ?? "";
+  const keywordParams = keywordFilter?.params ?? {};
+
+  const scoreMap = new Map<string, ScoredNode>();
+
+  // --- Vector search (per label) ---
+  let indexesToQuery: string[];
+  if (labels && labels.length > 0) {
+    indexesToQuery = labels
+      .map((l) => labelToIndex.get(l))
+      .filter((idx): idx is string => idx !== undefined);
+    if (indexesToQuery.length === 0) {
+      return { mode: "hybrid", results: [] };
+    }
+  } else {
+    indexesToQuery = [...new Set(labelToIndex.values())];
+  }
+
+  const scopeClause = allowedScopes
+    ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
+    : "";
+  const scopeParams = allowedScopes ? { allowedScopes } : {};
+  const agentClause = agentSlug
+    ? "AND node.agents IS NOT NULL AND $agentSlug IN node.agents"
+    : "";
+  const agentParams = agentSlug ? { agentSlug } : {};
+
+  for (const indexName of indexesToQuery) {
+    const vectorResult = await session.run(
+      `CALL db.index.vector.queryNodes($indexName, $limit, $embedding)
+       YIELD node, score
+       WHERE node.accountId = $accountId
+       ${scopeClause}
+       ${agentClause}
+       AND ${notTrashed("node")}
+       ${keywordClause}
+       RETURN node, score, labels(node) AS nodeLabels, elementId(node) AS nodeId
+       ORDER BY score DESC
+       LIMIT $limit`,
+      {
+        indexName,
+        embedding: queryEmbedding,
+        limit: int(limit),
+        accountId,
+        ...scopeParams,
+        ...agentParams,
+        ...keywordParams,
+      },
+    );
+    for (const record of vectorResult.records) {
+      const nodeId = record.get("nodeId") as string;
+      const scoreRaw = record.get("score");
+      const score = typeof scoreRaw === "number" ? scoreRaw : Number(scoreRaw);
+      const existing = scoreMap.get(nodeId);
+      if (existing) {
+        existing.vectorScore = Math.max(existing.vectorScore, score);
+      } else {
+        const node = record.get("node") as { properties: Record<string, unknown> };
+        scoreMap.set(nodeId, {
+          nodeId,
+          labels: record.get("nodeLabels") as string[],
+          properties: plainProperties(node.properties),
+          vectorScore: score,
+          bm25Score: 0,
+        });
+      }
+    }
+  }
+
+  // --- BM25 half ---
+  const bm25Hits = await bm25Only(session, params);
+  if (bm25Hits.length > 0) {
+    const rawScores = bm25Hits.map((h) => h.score);
+    const normalised = normaliseBm25Scores(rawScores);
+    for (let i = 0; i < bm25Hits.length; i++) {
+      mergeBm25Hit(scoreMap, bm25Hits[i], normalised[i]);
+    }
+  }
+
+  // --- Keyword subscriptions (scope-inclusive, agentSlug-bypassing) ---
+  if (keywordSubscriptions && keywordSubscriptions.length > 0) {
+    for (const kw of keywordSubscriptions) {
+      const kwHits = await bm25Only(session, {
+        query: kw,
+        accountId,
+        limit,
+        allowedScopes,
+      });
+      if (kwHits.length === 0) continue;
+      const rawScores = kwHits.map((h) => h.score);
+      const normalised = normaliseBm25Scores(rawScores);
+      for (let i = 0; i < kwHits.length; i++) {
+        mergeBm25Hit(scoreMap, kwHits[i], normalised[i]);
+      }
+    }
+
+    const propScopeClause = allowedScopes
+      ? "AND (node.scope IS NULL OR node.scope IN $allowedScopes)"
+      : "";
+    const propResult = await session.run(
+      `MATCH (node)
+       WHERE node.accountId = $accountId
+       AND ${notTrashed("node")}
+       AND node.keywords IS NOT NULL
+       AND ANY(kw IN $kwSubs WHERE ANY(nk IN node.keywords WHERE toLower(nk) = kw))
+       ${propScopeClause}
+       RETURN node, labels(node) AS nodeLabels, elementId(node) AS nodeId
+       LIMIT $limit`,
+      {
+        accountId,
+        kwSubs: keywordSubscriptions,
+        limit: int(limit),
+        ...(allowedScopes ? { allowedScopes } : {}),
+      },
+    );
+    for (const record of propResult.records) {
+      const nodeId = record.get("nodeId") as string;
+      const existing = scoreMap.get(nodeId);
+      if (existing) {
+        existing.bm25Score = Math.max(existing.bm25Score, 1.0);
+      } else {
+        const node = record.get("node") as { properties: Record<string, unknown> };
+        scoreMap.set(nodeId, {
+          nodeId,
+          labels: record.get("nodeLabels") as string[],
+          properties: plainProperties(node.properties),
+          vectorScore: 0,
+          bm25Score: 1.0,
+        });
+      }
+    }
+  }
+
+  // --- Merge & rank ---
+  const merged = [...scoreMap.values()]
+    .map((node) => ({
+      ...node,
+      combinedScore: VECTOR_WEIGHT * node.vectorScore + BM25_WEIGHT * node.bm25Score,
+    }))
+    .sort((a, b) => b.combinedScore - a.combinedScore)
+    .slice(0, limit);
+
+  // --- Graph expand ---
+  const results: SearchResult[] = [];
+  for (const node of merged) {
+    const result: SearchResult = {
+      nodeId: node.nodeId,
+      labels: node.labels,
+      properties: node.properties,
+      score: node.combinedScore,
+      related: [],
+    };
+    if (expandHops > 0) {
+      const expandScopeClause = allowedScopes
+        ? "AND (related.scope IS NULL OR related.scope IN $allowedScopes)"
+        : "";
+      const expandAgentClause = agentSlug
+        ? "AND (related.agents IS NULL OR $agentSlug IN related.agents)"
+        : "";
+      const expandResult = await session.run(
+        `MATCH (n)-[r]-(related)
+         WHERE elementId(n) = $nodeId
+         AND ${notTrashed("related")}
+         ${expandScopeClause}
+         ${expandAgentClause}
+         RETURN type(r) AS relType,
+                CASE WHEN startNode(r) = n THEN 'outgoing' ELSE 'incoming' END AS direction,
+                labels(related) AS relatedLabels,
+                related
+         LIMIT 20`,
+        { nodeId: node.nodeId, ...scopeParams, ...agentParams },
+      );
+      for (const rec of expandResult.records) {
+        const related = rec.get("related") as { properties: Record<string, unknown> };
+        result.related.push({
+          relationship: rec.get("relType") as string,
+          direction: rec.get("direction") as string,
+          labels: rec.get("relatedLabels") as string[],
+          properties: plainProperties(related.properties),
+        });
+      }
+    }
+    results.push(result);
+  }
+
+  return { mode: "hybrid", results };
+}
+
+function mergeBm25Hit(
+  map: Map<string, ScoredNode>,
+  hit: SearchHit,
+  normalisedScore: number,
+): void {
+  const existing = map.get(hit.nodeId);
+  if (existing) {
+    existing.bm25Score = Math.max(existing.bm25Score, normalisedScore);
+  } else {
+    map.set(hit.nodeId, {
+      nodeId: hit.nodeId,
+      labels: hit.labels,
+      properties: hit.properties,
+      vectorScore: 0,
+      bm25Score: normalisedScore,
+    });
+  }
+}
+
+/** Strip `embedding` and unwrap Neo4j Integers into JS numbers. */
+function plainProperties(properties: Record<string, unknown>): Record<string, unknown> {
+  const plain: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(properties)) {
+    if (key === "embedding") continue;
+    if (value && typeof value === "object" && "toNumber" in value) {
+      plain[key] = (value as { toNumber(): number }).toNumber();
+    } else {
+      plain[key] = value;
+    }
+  }
+  return plain;
+}

package/payload/platform/lib/graph-search/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["src/__tests__"]
+}

package/payload/platform/lib/graph-search/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: false,
+    include: ['src/__tests__/**/*.test.ts'],
+  },
+});

package/payload/platform/lib/graph-write/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Write doctrine (Task 673): a node without at least one adjacency is noise,
+ * not knowledge. `writeNodeWithEdges` is the single primitive every graph
+ * writer should call; it rejects zero-relationship writes, verifies every
+ * relationship target resolves before the node is created, and commits the
+ * node + all edges in one managed transaction. Provenance is stamped on the
+ * node as flattened `createdBy*` properties (Neo4j does not persist nested
+ * maps, and flat props are queryable — `MATCH (n) WHERE n.createdBySession
+ * = $id RETURN n` is the forensic entry point).
+ *
+ * Rejection paths (every one emits a stderr log the admin server pipes to
+ * server.log, so orphan pressure is visible per-write not just in the
+ * hourly [graph-health] signal):
+ *   - zero relationships      → `[graph-write] reject reason=zero-relationships`
+ *   - unresolved target id    → `[graph-write] reject reason=unresolved-target`
+ *
+ * The `createdBy.agent` field is advisory, not authoritative — it is sourced
+ * from the MCP server's AGENT_SLUG env var, which is set by the trusted
+ * spawning code (admin server / workflow runner). A misconfigured spawner
+ * will write "unknown"; that's the signal something is wrong. Do not use
+ * this field for access control — it is forensic, not a security boundary.
+ */
+import type { Session } from "neo4j-driver";
+export interface GraphRelationship {
+    type: string;
+    direction: "outgoing" | "incoming";
+    targetNodeId: string;
+}
+export interface CreatedBy {
+    /** Agent slug (e.g. "maxy-admin", "whatsapp-public") for LLM-tool writes. */
+    agent?: string;
+    /** Session correlation id — same string across every node written in a conversation turn. */
+    session?: string;
+    /** MCP tool name ("memory-write", "contact-create", ...) for LLM-tool writes. */
+    tool?: string;
+    /** Subsystem name ("workflow-execute", "persist-tool-call", ...) for system writes. */
+    source?: string;
+}
+export interface WriteNodeWithEdgesParams {
+    session: Session;
+    labels: string[];
+    props: Record<string, unknown>;
+    /** At least one relationship is required — zero-rel writes are rejected. */
+    relationships: GraphRelationship[];
+    createdBy: CreatedBy;
+}
+export interface WriteNodeResult {
+    nodeId: string;
+    labels: string[];
+    edgesCreated: number;
+}
+/** Stamp flattened provenance into node properties. */
+export declare function stampCreatedBy(props: Record<string, unknown>, createdBy: CreatedBy): Record<string, unknown>;
+/**
+ * Enforce the write doctrine: node + ≥1 edge, transactional, provenance stamped.
+ * The label and relationship type strings are interpolated into Cypher — the
+ * caller must constrain them via Zod/schema before calling. Backticks are
+ * stripped to defeat the only Cypher escape char.
+ */
+export declare function writeNodeWithEdges(params: WriteNodeWithEdgesParams): Promise<WriteNodeResult>;
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/lib/graph-write/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;IACnC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,4EAA4E;IAC5E,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,uDAAuD;AACvD,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,SAAS,EAAE,SAAS,GACnB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,eAAe,CAAC,CAuF1B"}

package/payload/platform/lib/graph-write/dist/index.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Write doctrine (Task 673): a node without at least one adjacency is noise,
+ * not knowledge. `writeNodeWithEdges` is the single primitive every graph
+ * writer should call; it rejects zero-relationship writes, verifies every
+ * relationship target resolves before the node is created, and commits the
+ * node + all edges in one managed transaction. Provenance is stamped on the
+ * node as flattened `createdBy*` properties (Neo4j does not persist nested
+ * maps, and flat props are queryable — `MATCH (n) WHERE n.createdBySession
+ * = $id RETURN n` is the forensic entry point).
+ *
+ * Rejection paths (every one emits a stderr log the admin server pipes to
+ * server.log, so orphan pressure is visible per-write not just in the
+ * hourly [graph-health] signal):
+ *   - zero relationships      → `[graph-write] reject reason=zero-relationships`
+ *   - unresolved target id    → `[graph-write] reject reason=unresolved-target`
+ *
+ * The `createdBy.agent` field is advisory, not authoritative — it is sourced
+ * from the MCP server's AGENT_SLUG env var, which is set by the trusted
+ * spawning code (admin server / workflow runner). A misconfigured spawner
+ * will write "unknown"; that's the signal something is wrong. Do not use
+ * this field for access control — it is forensic, not a security boundary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stampCreatedBy = stampCreatedBy;
+exports.writeNodeWithEdges = writeNodeWithEdges;
+/** Stamp flattened provenance into node properties. */
+function stampCreatedBy(props, createdBy) {
+    return {
+        ...props,
+        createdByAgent: createdBy.agent ?? "unknown",
+        createdBySession: createdBy.session ?? "unknown",
+        createdByTool: createdBy.tool ?? null,
+        createdBySource: createdBy.source ?? null,
+    };
+}
+/**
+ * Enforce the write doctrine: node + ≥1 edge, transactional, provenance stamped.
+ * The label and relationship type strings are interpolated into Cypher — the
+ * caller must constrain them via Zod/schema before calling. Backticks are
+ * stripped to defeat the only Cypher escape char.
+ */
+async function writeNodeWithEdges(params) {
+    const { session, labels, props, relationships, createdBy } = params;
+    const agentLabel = createdBy.agent ?? createdBy.source ?? "unknown";
+    const labelCsv = labels.join(",");
+    if (!relationships || relationships.length < 1) {
+        process.stderr.write(`[graph-write] reject reason=zero-relationships labels=${labelCsv} agent=${agentLabel}\n`);
+        throw new Error("Write doctrine violated: a node must be created with at least one relationship. See .docs/neo4j.md (Write doctrine).");
+    }
+    const labelStr = labels.map((l) => `\`${l.replace(/`/g, "")}\``).join(":");
+    const nodeProps = stampCreatedBy(props, createdBy);
+    return await session.executeWrite(async (tx) => {
+        const targetIds = relationships.map((r) => r.targetNodeId);
+        const check = await tx.run(`UNWIND $ids AS id MATCH (t) WHERE elementId(t) = id RETURN count(DISTINCT t) AS found`, { ids: targetIds });
+        const found = check.records[0].get("found").toNumber();
+        const uniqueRequested = new Set(targetIds).size;
+        if (found !== uniqueRequested) {
+            process.stderr.write(`[graph-write] reject reason=unresolved-target labels=${labelCsv} agent=${agentLabel} requested=${uniqueRequested} found=${found}\n`);
+            throw new Error(`Write doctrine violated: ${uniqueRequested - found} of ${uniqueRequested} relationship target(s) did not resolve (elementId mismatch). No node created.`);
+        }
+        const nodeRes = await tx.run(`CREATE (n:${labelStr} $props) RETURN elementId(n) AS nodeId, labels(n) AS nodeLabels`, { props: nodeProps });
+        const nodeId = nodeRes.records[0].get("nodeId");
+        const nodeLabels = nodeRes.records[0].get("nodeLabels");
+        // Neo4j Community's default isolation is read-committed (not snapshot)
+        // — a target elementId that resolved during the pre-check can be
+        // deleted by a concurrent transaction before the per-edge CREATE below
+        // runs. If that happens, `MATCH (a), (b)` returns 0 rows and the CREATE
+        // quietly produces no edge. Per-edge counter inspection catches the
+        // race: any zero-result CREATE throws inside the transaction callback,
+        // so `executeWrite` rolls the node back — no silent-orphan path.
+        let edgesCreated = 0;
+        for (const rel of relationships) {
+            const type = rel.type.replace(/`/g, "");
+            const q = rel.direction === "outgoing"
+                ? `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (a)-[:\`${type}\`]->(b)`
+                : `MATCH (a), (b) WHERE elementId(a) = $from AND elementId(b) = $to CREATE (b)-[:\`${type}\`]->(a)`;
+            const r = await tx.run(q, { from: nodeId, to: rel.targetNodeId });
+            const created = r.summary.counters.updates().relationshipsCreated;
+            if (created === 0) {
+                process.stderr.write(`[graph-write] reject reason=unresolved-target-on-create labels=${labelCsv} agent=${agentLabel} relType=${rel.type} targetId=${rel.targetNodeId}\n`);
+                throw new Error(`Write doctrine violated: relationship CREATE to target ${rel.targetNodeId} produced 0 edges (target likely deleted concurrently after pre-check). Transaction rolled back.`);
+            }
+            edgesCreated += created;
+        }
+        if (edgesCreated !== relationships.length) {
+            // Defensive: should be unreachable given the per-edge check above.
+            // The rollback throws loudly so regression shows rather than a
+            // silent commit with edgesCreated < requested.
+            process.stderr.write(`[graph-write] reject reason=edge-count-mismatch labels=${labelCsv} agent=${agentLabel} requested=${relationships.length} created=${edgesCreated}\n`);
+            throw new Error(`Write doctrine violated: expected ${relationships.length} edges, created ${edgesCreated}. Transaction rolled back.`);
+        }
+        process.stderr.write(`[graph-write] accepted labels=${labelCsv} edges=${edgesCreated} createdByAgent=${createdBy.agent ?? "unknown"} createdByTool=${createdBy.tool ?? createdBy.source ?? "unknown"}\n`);
+        return { nodeId, labels: nodeLabels, edgesCreated };
+    });
+}
+//# sourceMappingURL=index.js.map

package/payload/platform/lib/graph-write/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AAqCH,wCAWC;AAQD,gDAyFC;AA7GD,uDAAuD;AACvD,SAAgB,cAAc,CAC5B,KAA8B,EAC9B,SAAoB;IAEpB,OAAO;QACL,GAAG,KAAK;QACR,cAAc,EAAE,SAAS,CAAC,KAAK,IAAI,SAAS;QAC5C,gBAAgB,EAAE,SAAS,CAAC,OAAO,IAAI,SAAS;QAChD,aAAa,EAAE,SAAS,CAAC,IAAI,IAAI,IAAI;QACrC,eAAe,EAAE,SAAS,CAAC,MAAM,IAAI,IAAI;KAC1C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACI,KAAK,UAAU,kBAAkB,CACtC,MAAgC;IAEhC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAEpE,MAAM,UAAU,GAAG,SAAS,CAAC,KAAK,IAAI,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC;IACpE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAElC,IAAI,CAAC,aAAa,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,yDAAyD,QAAQ,UAAU,UAAU,IAAI,CAC1F,CAAC;QACF,MAAM,IAAI,KAAK,CACb,sHAAsH,CACvH,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3E,MAAM,SAAS,GAAG,cAAc,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IAEnD,OAAO,MAAM,OAAO,CAAC,YAAY,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE;QAC7C,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,GAAG,CACxB,uFAAuF,EACvF,EAAE,GAAG,EAAE,SAAS,EAAE,CACnB,CAAC;QACF,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;QACvD,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC;QAChD,IAAI,KAAK,KAAK,eAAe,EAAE,CAAC;YAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wDAAwD,QAAQ,UAAU,UAAU,cAAc,eAAe,UAAU,KAAK,IAAI,CACrI,CAAC;YACF,MAAM,IAAI,KAAK,CACb,4BAA4B,eAAe,GAAG,KAAK,OAAO,eAAe,gFAAgF,CAC1J,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,GAAG,CAC1B,aAAa,QAAQ,iEAAiE,EACtF,EAAE,KAAK,EAAE,SAAS,EAAE,CACrB,CAAC;QACF,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAW,CAAC;QAC1D,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,YAAY,CAAa,CAAC;QAEpE,uEAAuE;QACvE,iEAAiE;QACjE,uEAAuE;QACvE,wEAAwE;QACxE,oEAAoE;QACpE,uEAAuE;QACvE,iEAAiE;QACjE,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,KAAK,MAAM,GAAG,IAAI,aAAa,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACxC,MAAM,CAAC,GACL,GAAG,CAAC,SAAS,KAAK,UAAU;gBAC1B,CAAC,CAAC,mFAAmF,IAAI,UAAU;gBACnG,CAAC,CAAC,mFAAmF,IAAI,UAAU,CAAC;YACxG,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,CAAC,YAAY,EAAE,CAAC,CAAC;YAClE,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,oBAAoB,CAAC;YAClE,IAAI,OAAO,KAAK,CAAC,EAAE,CAAC;gBAClB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kEAAkE,QAAQ,UAAU,UAAU,YAAY,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,YAAY,IAAI,CACpJ,CAAC;gBACF,MAAM,IAAI,KAAK,CACb,0DAA0D,GAAG,CAAC,YAAY,kGAAkG,CAC7K,CAAC;YACJ,CAAC;YACD,YAAY,IAAI,OAAO,CAAC;QAC1B,CAAC;QAED,IAAI,YAAY,KAAK,aAAa,CAAC,MAAM,EAAE,CAAC;YAC1C,mEAAmE;YACnE,+DAA+D;YAC/D,+CAA+C;YAC/C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,0DAA0D,QAAQ,UAAU,UAAU,cAAc,aAAa,CAAC,MAAM,YAAY,YAAY,IAAI,CACrJ,CAAC;YACF,MAAM,IAAI,KAAK,CACb,qCAAqC,aAAa,CAAC,MAAM,mBAAmB,YAAY,4BAA4B,CACrH,CAAC;QACJ,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,iCAAiC,QAAQ,UAAU,YAAY,mBAAmB,SAAS,CAAC,KAAK,IAAI,SAAS,kBAAkB,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,MAAM,IAAI,SAAS,IAAI,CACpL,CAAC;QAEF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;IACtD,CAAC,CAAC,CAAC;AACL,CAAC"}