@rubytech/create-maxy 1.0.743 → 1.0.745

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

@@ -28,8 +28,26 @@ import { accessSync, appendFileSync, constants, mkdirSync, readFileSync, statSyn
 import { resolve } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { initStderrTee } from "../../mcp-stderr-tee/dist/index.js";
-import { validate as validateCypher, type UnknownToken } from "./cypher-validate.js";
-import { SchemaCache, neo4jSchemaFetcher } from "./schema-cache.js";
+import {
+  validate as validateCypher,
+  type ForbiddenPattern,
+  type UnknownToken,
+} from "./cypher-validate.js";
+import {
+  auditCypherWrite,
+  formatAuditLine,
+  type AuditWarning,
+} from "../../graph-write/dist/audit.js";
+import { SchemaCache, getSharedDriver, neo4jSchemaFetcher } from "./schema-cache.js";
+import { rewriteWithProvenanceStamps } from "./cypher-rewrite-stamp.js";
+import {
+  OrphanRollbackError,
+  runWriteTxBody,
+  synthesiseOrphanRollback,
+  synthesiseShimError,
+  synthesiseWriteResponse,
+  type GraphDriver,
+} from "./cypher-shim-write.js";
 
 const SERVER_NAME = "graph";
 const UPSTREAM_PACKAGE = "mcp-neo4j-cypher@0.6.0";
@@ -162,7 +180,15 @@ const neo4jPassword = resolvePassword();
 const portMatch = /:(\d+)$/.exec(neo4jUri);
 const neo4jPort = portMatch ? portMatch[1] : "?";
 const namespace = process.env.NEO4J_NAMESPACE ?? "maxy-graph";
-const readOnly = process.env.NEO4J_READ_ONLY ?? "true";
+// Task 796 — default flipped from "true" to "false" so the upstream
+// `mcp-neo4j-cypher` registers `write_neo4j_cypher` alongside the read tool.
+// Per-agent gating via the `tools:` frontmatter list confines the surface:
+// only `database-operator.md` lists `mcp__graph__maxy-graph-write_neo4j_cypher`,
+// and the parent admin spawn only allow-lists it via `ADMIN_CORE_TOOLS` so
+// the operator subagent inherits permission. Operators who set
+// NEO4J_READ_ONLY=true explicitly (e.g. dev sandboxes) still get the
+// upstream's read-only mode.
+const readOnly = process.env.NEO4J_READ_ONLY ?? "false";
 const responseTokenLimit = process.env.NEO4J_RESPONSE_TOKEN_LIMIT ?? "20000";
 
 const childEnv: NodeJS.ProcessEnv = {
@@ -250,18 +276,31 @@ child.stderr.on("data", (chunk: Buffer) => {
   process.stderr.write(chunk);
 });
 
-// --- JSON-RPC call correlation + validation (Task 654) ---
+// --- JSON-RPC call correlation + validation (Task 654, Task 796) ---
 // tools/call is the only method we time or validate. For read/write cypher
 // calls, the line is validated against the schema cache before forwarding.
 // Write-path rejection: synthesised MCP tool-error response on stdout, NOT
-// forwarded. Read-path rejection: forwarded, with warnings appendix prepended
-// to response.content[0].text.
+// forwarded — fires only on forbidden DDL/admin patterns (Task 796 reframe;
+// unknown labels/types in writes are warnings, not rejections, since
+// operators legitimately introduce new labels via REMOVE/SET). Read-path
+// rejection: forwarded, with warnings appendix prepended to
+// response.content[0].text.
 interface PendingCall {
   method: string;
   cypherPrefix: string | null;
+  /** Full cypher body — Task 796: needed for the post-write audit's static parse. */
+  cypherFull: string | null;
+  isWrite: boolean;
+  /** Caller-supplied sessionId param, used by the post-write audit emission. */
+  sessionIdParam: string | null;
   startMs: number;
   validated: boolean;
   readWarnings: UnknownToken[];
+  /** Task 796: unknown relationship tokens carried from request to response so
+   *  the audit emits one `unknown-type-warning` line per unknown after the
+   *  upstream commits (the validator only detected them; emission waits for
+   *  the post-write line family). */
+  writeUnknownTokens: UnknownToken[];
 }
 const pending = new Map<string | number, PendingCall>();
 
@@ -296,6 +335,39 @@ function extractCypherFull(args: Record<string, unknown> | undefined): string |
   return typeof q === "string" ? q : null;
 }
 
+// Task 796: the operator's Graph Stewardship Doctrine (Rule 3) requires
+// `r.createdBySession = $sessionId` on every write. The post-write audit
+// emits the `[graph-cypher-write] accepted` line with this sessionId so
+// later forensic queries can join the audit log to the persisted node set
+// via `WHERE n.createdBySession = $sessionId`. Returns null if the operator
+// did not pass a sessionId param — the audit then emits sessionId=unknown
+// and the missing-provenance warning fires from the static parse.
+function extractSessionIdParam(args: Record<string, unknown> | undefined): string | null {
+  if (!args) return null;
+  const params = args["params"];
+  if (!params || typeof params !== "object") return null;
+  const sid = (params as Record<string, unknown>)["sessionId"];
+  return typeof sid === "string" ? sid : null;
+}
+
+// Task 796: parse the upstream `mcp-neo4j-cypher` write response counters.
+// The upstream emits human-readable summary phrases ("3 nodes created", "4
+// relationships created") in the result.content[0].text. Defensive regex —
+// missing phrases coerce to 0 so the accepted line still emits with
+// observable nodesCreated/relsCreated fields.
+function parseWriteCounters(
+  result: JsonRpcMessage["result"],
+): { nodes: number; rels: number } {
+  if (!result?.content || !Array.isArray(result.content)) return { nodes: 0, rels: 0 };
+  const text = result.content[0]?.text ?? "";
+  const nodesMatch = text.match(/(\d+)\s*nodes?\s*created/i);
+  const relsMatch = text.match(/(\d+)\s*relationships?\s*created/i);
+  return {
+    nodes: nodesMatch ? parseInt(nodesMatch[1], 10) : 0,
+    rels: relsMatch ? parseInt(relsMatch[1], 10) : 0,
+  };
+}
+
 function truncateForLog(cypher: string): string {
   return truncate(cypher.replace(/\s+/g, " ").trim(), 80);
 }
@@ -340,6 +412,33 @@ function synthesiseRejection(id: string | number, unknown: UnknownToken[]): stri
   return JSON.stringify(envelope);
 }
 
+// Task 796: synthesised rejection for forbidden DDL/admin patterns. Fired
+// from the write-mode validator when the operator (or a regression in admin
+// dispatch) tries `DROP DATABASE`, `CREATE INDEX/CONSTRAINT`, `CALL dbms.*`,
+// or `CALL db.create*`. The text names every matched pattern so the operator
+// reads exactly which clause tripped the gate.
+function synthesiseForbiddenRejection(
+  id: string | number,
+  forbidden: ForbiddenPattern[],
+): string {
+  const lines = forbidden.map(
+    (f) => `  - ${f.kind}: matched "${f.match.replace(/"/g, "'")}" — ${f.hint}`,
+  );
+  const text =
+    `forbidden cypher pattern — write NOT executed\n${lines.join("\n")}\n\n` +
+    `Index/constraint DDL is admin-owned (seed-neo4j.sh). Security CALL surface ` +
+    `(dbms.*, db.create*) is not exposed to the operator role.`;
+  const envelope = {
+    jsonrpc: "2.0",
+    id,
+    result: {
+      content: [{ type: "text", text }],
+      isError: true,
+    },
+  };
+  return JSON.stringify(envelope);
+}
+
 function wrapReadWarnings(msg: JsonRpcMessage, warnings: UnknownToken[]): string {
   const warningText = `${renderUnknownTokens(warnings, "warning")}\n\n--- results below (executed despite unknown tokens) ---\n`;
   const original = msg.result?.content ?? [];
@@ -353,6 +452,174 @@ function wrapReadWarnings(msg: JsonRpcMessage, warnings: UnknownToken[]): string
   return JSON.stringify(wrapped);
 }
 
+// --- Task 797: shim-owned write path -----------------------------------
+// write_neo4j_cypher is intercepted (not forwarded to upstream). The shim
+// runs the operator's cypher inside its own driver session under
+// `executeWrite`, so provenance auto-stamping and orphan-rollback are
+// transactionally atomic. Reads still pass through to upstream unchanged.
+// Pure helpers (runWriteTxBody, synthesise*, OrphanRollbackError) live in
+// cypher-shim-write.ts so they can be unit-tested without booting this
+// module's stdin/stdout pipe and uvx spawn.
+
+async function runShimWriteCypher(
+  id: string | number,
+  cypherFull: string,
+  cypherPrefix: string,
+  sessionIdParam: string | null,
+  operatorArgs: Record<string, unknown> | undefined,
+  startMs: number,
+  writeUnknownTokens: UnknownToken[],
+  validated: boolean,
+): Promise<void> {
+  const agentName = process.env.AGENT_SLUG ?? "unknown";
+  const sessionIdField =
+    sessionIdParam ?? process.env.SESSION_ID ?? "unknown";
+  const operatorParams =
+    (operatorArgs?.["params"] as Record<string, unknown> | undefined) ?? {};
+  const safePrefix = cypherPrefix.replace(/"/g, "'");
+
+  let rewrite: ReturnType<typeof rewriteWithProvenanceStamps>;
+  try {
+    rewrite = rewriteWithProvenanceStamps(cypherFull);
+  } catch (err) {
+    // Defensive — the rewriter is regex-only with no catastrophic-backtrack
+    // patterns, but a thrown error before driver acquisition would otherwise
+    // emit no [graph-query] line at all (review F3).
+    const errMsg = err instanceof Error ? err.message : String(err);
+    console.error(
+      `[graph-query] op=${WRITE_CYPHER_TOOL} brand=${brand} port=${neo4jPort} cypher="${safePrefix}" error="rewrite-failed: ${errMsg.replace(/"/g, "'")}" validated=${validated} ms=${Date.now() - startMs}`,
+    );
+    process.stdout.write(
+      `${synthesiseShimError(id, "cypher rewrite failed — write NOT executed", errMsg)}\n`,
+    );
+    return;
+  }
+  if (rewrite.stampsAppended > 0) {
+    console.error(
+      `[graph-cypher-write] auto-stamp applied query="${safePrefix}" creates=${rewrite.stampsAppended}`,
+    );
+  }
+
+  let driver: GraphDriver;
+  try {
+    driver = (await getSharedDriver(resolvedNeo4jUri, neo4jUser, neo4jPassword)) as GraphDriver;
+  } catch (err) {
+    const errMsg = err instanceof Error ? err.message : String(err);
+    console.error(
+      `[graph-query] op=${WRITE_CYPHER_TOOL} brand=${brand} port=${neo4jPort} cypher="${safePrefix}" error="driver-unavailable: ${errMsg.replace(/"/g, "'")}" validated=${validated} ms=${Date.now() - startMs}`,
+    );
+    process.stdout.write(
+      `${synthesiseShimError(id, "graph driver unavailable — write NOT executed", errMsg)}\n`,
+    );
+    return;
+  }
+
+  const session = driver.session();
+  let outcome: { nodesCreated: number; relsCreated: number; propertiesSet: number; serializedRecords: Array<Record<string, unknown>> } | null = null;
+
+  try {
+    outcome = await session.executeWrite((tx) =>
+      runWriteTxBody(tx, rewrite.cypher, operatorParams, {
+        agent: agentName,
+        session: sessionIdField,
+      }),
+    );
+  } catch (err) {
+    if (err instanceof OrphanRollbackError) {
+      console.error(
+        `[graph-cypher-write] orphan-rollback query="${safePrefix}" orphanLabels=${err.sampleLabels.join(",")}`,
+      );
+      console.error(
+        formatAuditLine({
+          kind: "orphan-warning",
+          cypherPrefix,
+          orphanIds: err.orphanIds,
+        }),
+      );
+      console.error(
+        `[graph-query] op=${WRITE_CYPHER_TOOL} brand=${brand} port=${neo4jPort} cypher="${safePrefix}" rolledBack=true orphans=${err.orphanIds.length} validated=${validated} ms=${Date.now() - startMs}`,
+      );
+      process.stdout.write(
+        `${synthesiseOrphanRollback(id, err.orphanIds.length, err.sampleLabels)}\n`,
+      );
+    } else {
+      const errMsg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[graph-query] op=${WRITE_CYPHER_TOOL} brand=${brand} port=${neo4jPort} cypher="${safePrefix}" error="${errMsg.replace(/"/g, "'")}" validated=${validated} ms=${Date.now() - startMs}`,
+      );
+      process.stdout.write(
+        `${synthesiseShimError(id, "Neo4j error", errMsg)}\n`,
+      );
+    }
+    return;
+  } finally {
+    await session.close().catch(() => {
+      /* session already closed by the driver on commit/rollback */
+    });
+  }
+
+  // outcome is non-null on the success path (the catch above returns early
+  // on rollback / shim error). Defensive narrow.
+  if (!outcome) return;
+
+  console.error(
+    `[graph-query] op=${WRITE_CYPHER_TOOL} brand=${brand} port=${neo4jPort} cypher="${safePrefix}" rows=${outcome.serializedRecords.length} validated=${validated} ms=${Date.now() - startMs}`,
+  );
+  console.error(
+    formatAuditLine({
+      kind: "accepted",
+      cypherPrefix,
+      nodesCreated: outcome.nodesCreated,
+      relsCreated: outcome.relsCreated,
+      agentName,
+      sessionId: sessionIdField,
+    }),
+  );
+
+  for (const t of writeUnknownTokens.filter((u) => u.kind === "relationship")) {
+    console.error(
+      formatAuditLine({
+        kind: "unknown-type-warning",
+        cypherPrefix,
+        type: t.token,
+      }),
+    );
+  }
+
+  const auditWarnings: AuditWarning[] = auditCypherWrite({
+    cypher: rewrite.cypher,
+    schema: schemaCache.snapshot(),
+    agentName,
+    sessionId: sessionIdField,
+    nodesCreated: outcome.nodesCreated,
+    relsCreated: outcome.relsCreated,
+    orphanIds: [],
+  });
+  for (const w of auditWarnings) {
+    if (w.kind === "missing-provenance-warning") {
+      console.error(
+        formatAuditLine({
+          kind: "missing-provenance-warning",
+          cypherPrefix,
+          created: w.created,
+          stamped: w.stamped,
+        }),
+      );
+    }
+    // unknown-type already emitted from the validator's writeUnknownTokens above;
+    // orphan-warning fires only on the rollback path.
+  }
+
+  process.stdout.write(
+    `${synthesiseWriteResponse(id, {
+      nodesCreated: outcome.nodesCreated,
+      relsCreated: outcome.relsCreated,
+      propertiesSet: outcome.propertiesSet,
+      records: outcome.serializedRecords,
+    })}\n`,
+  );
+}
+
 type RequestDecision = "forward" | "intercepted";
 
 function handleRequestLine(line: string): RequestDecision {
@@ -369,13 +636,21 @@ function handleRequestLine(line: string): RequestDecision {
   const cypherPrefix = cypherFull ? truncateForLog(cypherFull) : null;
   const isCypherCall =
     methodName === READ_CYPHER_TOOL || methodName === WRITE_CYPHER_TOOL;
+  const isWriteCall = methodName === WRITE_CYPHER_TOOL;
+  const sessionIdParam = isWriteCall
+    ? extractSessionIdParam(msg.params?.arguments)
+    : null;
 
   const entry: PendingCall = {
     method: methodName,
     cypherPrefix,
+    cypherFull,
+    isWrite: isWriteCall,
+    sessionIdParam,
     startMs: Date.now(),
     validated: false,
     readWarnings: [],
+    writeUnknownTokens: [],
   };
 
   if (!isCypherCall || !cypherFull) {
@@ -383,25 +658,77 @@ function handleRequestLine(line: string): RequestDecision {
     return "forward";
   }
 
-  const isWrite = methodName === WRITE_CYPHER_TOOL;
+  // Task 797: writes are intercepted into the shim-owned driver path.
+  // Helper so each branch below routes consistently.
+  const interceptWrite = (): RequestDecision => {
+    void runShimWriteCypher(
+      msg.id as string | number,
+      cypherFull,
+      cypherPrefix ?? "",
+      sessionIdParam,
+      msg.params?.arguments,
+      entry.startMs,
+      entry.writeUnknownTokens,
+      entry.validated,
+    ).catch((err) => {
+      // Defensive catch — runShimWriteCypher already handles its own errors,
+      // but never let an unexpected throw leak past this point.
+      const errMsg = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[graph-mcp] runShimWriteCypher unhandled error: ${errMsg.replace(/"/g, "'")}`,
+      );
+      try {
+        process.stdout.write(
+          `${synthesiseShimError(msg.id as string | number, "shim-internal error", errMsg)}\n`,
+        );
+      } catch {
+        /* stdout closed */
+      }
+    });
+    return "intercepted";
+  };
+
   const snapshot = schemaCache.snapshot();
   const cacheReady = schemaCache.ready();
 
   if (!cacheReady) {
     console.error(
-      `[cypher-validate] tool=${isWrite ? "write" : "read"} outcome=skipped reason=cache-not-ready cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
+      `[cypher-validate] tool=${isWriteCall ? "write" : "read"} outcome=skipped reason=cache-not-ready cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
     );
+    if (isWriteCall) {
+      // Task 797: still rewrite + run inside shim tx even when validator
+      // is cold. Auto-stamp + orphan rollback don't depend on schema.
+      return interceptWrite();
+    }
     pending.set(msg.id, entry);
     return "forward";
   }
 
-  const result = validateCypher(cypherFull, snapshot);
+  const result = validateCypher(cypherFull, snapshot, {
+    mode: isWriteCall ? "write" : "read",
+  });
   entry.validated = true;
 
+  // Task 796: forbidden DDL/admin → hard reject in write mode (only path
+  // that produces forbidden entries; read mode never populates them).
+  if (isWriteCall && result.forbidden.length > 0) {
+    const forbiddenSummary = result.forbidden.map((f) => f.kind).join(",");
+    console.error(
+      `[cypher-validate] tool=write outcome=rejected forbidden=${forbiddenSummary} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
+    );
+    const response = synthesiseForbiddenRejection(msg.id, result.forbidden);
+    process.stdout.write(`${response}\n`);
+    console.error(
+      `[graph-query] op=${methodName} brand=${brand} port=${neo4jPort} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}" rejected=true forbidden=${forbiddenSummary} validated=true ms=${Date.now() - entry.startMs}`,
+    );
+    return "intercepted";
+  }
+
   if (result.ok) {
     console.error(
-      `[cypher-validate] tool=${isWrite ? "write" : "read"} outcome=accepted labels=${result.labelTokens.length} relationships=${result.edgeTokens.length}`,
+      `[cypher-validate] tool=${isWriteCall ? "write" : "read"} outcome=accepted labels=${result.labelTokens.length} relationships=${result.edgeTokens.length}`,
     );
+    if (isWriteCall) return interceptWrite();
     pending.set(msg.id, entry);
     return "forward";
   }
@@ -411,16 +738,17 @@ function handleRequestLine(line: string): RequestDecision {
     .map((u) => `${u.kind}:${u.token}`)
     .join(",");
 
-  if (isWrite) {
-    console.error(
-      `[cypher-validate] tool=write outcome=rejected unknown=${tokenSummary} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
-    );
-    const response = synthesiseRejection(msg.id, result.unknown);
-    process.stdout.write(`${response}\n`);
+  if (isWriteCall) {
+    // Task 796: write mode treats unknown tokens as soft warnings — operators
+    // legitimately introduce new labels (REMOVE n:Old SET n:New) and edges
+    // pending an ontology update. The post-write audit emits one
+    // unknown-type-warning per unknown so operators see the gap; the cypher
+    // still commits via the shim-owned write path (Task 797).
+    entry.writeUnknownTokens = result.unknown;
     console.error(
-      `[graph-query] op=${methodName} brand=${brand} port=${neo4jPort} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}" rejected=true validated=true ms=${Date.now() - entry.startMs}`,
+      `[cypher-validate] tool=write outcome=warned unknown=${tokenSummary} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
     );
-    return "intercepted";
+    return interceptWrite();
   }
 
   entry.readWarnings = result.unknown;
@@ -456,6 +784,75 @@ function handleResponseLine(line: string): string | null {
   console.error(
     `[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} rows=${rows} ${validatedField}${warnedField} ms=${elapsed}`,
   );
+
+  // Task 796 — post-write audit. The shim emits the `[graph-cypher-write]`
+  // family alongside the existing `[graph-query]` line so operators have a
+  // dedicated stream to grep without read-side noise. Static-only audit:
+  // unknown-type and missing-provenance warnings come from regex over the
+  // cypher body. Dynamic orphan detection (querying Neo4j for nodes
+  // matching createdBySession=$id AND NOT (n)--()) is deferred to Task 797
+  // — the audit module's `orphanIds` input stays empty here, the
+  // `[graph-cypher-write] orphan-warning` line never fires from production
+  // until that wires up.
+  if (p.isWrite && p.cypherFull && msg.result && !msg.result.isError) {
+    const counters = parseWriteCounters(msg.result);
+    const cypherPrefix = p.cypherPrefix ?? "";
+    const agentName = process.env.AGENT_SLUG ?? "unknown";
+    const sessionIdField = p.sessionIdParam ?? "unknown";
+    const snapshot = schemaCache.snapshot();
+    console.error(
+      formatAuditLine({
+        kind: "accepted",
+        cypherPrefix,
+        nodesCreated: counters.nodes,
+        relsCreated: counters.rels,
+        agentName,
+        sessionId: sessionIdField,
+      }),
+    );
+    const auditWarnings: AuditWarning[] = auditCypherWrite({
+      cypher: p.cypherFull,
+      schema: snapshot,
+      agentName,
+      sessionId: sessionIdField,
+      nodesCreated: counters.nodes,
+      relsCreated: counters.rels,
+      orphanIds: [],
+    });
+    for (const w of auditWarnings) {
+      switch (w.kind) {
+        case "unknown-type-warning":
+          console.error(
+            formatAuditLine({
+              kind: "unknown-type-warning",
+              cypherPrefix,
+              type: w.type,
+            }),
+          );
+          break;
+        case "missing-provenance-warning":
+          console.error(
+            formatAuditLine({
+              kind: "missing-provenance-warning",
+              cypherPrefix,
+              created: w.created,
+              stamped: w.stamped,
+            }),
+          );
+          break;
+        case "orphan-warning":
+          console.error(
+            formatAuditLine({
+              kind: "orphan-warning",
+              cypherPrefix,
+              orphanIds: w.orphanIds,
+            }),
+          );
+          break;
+      }
+    }
+  }
+
   if (p.readWarnings.length > 0) {
     try {
       return wrapReadWarnings(msg, p.readWarnings);

package/payload/platform/lib/graph-mcp/src/schema-cache.ts

@@ -156,20 +156,50 @@ export class SchemaCache {
 }
 
 /**
- * Build a SchemaFetcher over a long-lived neo4j-driver Driver. Each call
- * opens a fresh session (cheap, sub-ms) and closes it in finally so the
- * driver's connection pool stays small. Consumer owns the driver lifecycle.
+ * Module-scope driver singleton (Task 797). Both the schema-cache and the
+ * write-path (graph-mcp/src/index.ts `runShimWriteCypher`) borrow sessions
+ * from the same `neo4j-driver` Driver instance — one connection pool per
+ * process. The first call binds the URI/credentials; subsequent calls
+ * return the same driver regardless of arguments. The driver lives for
+ * the process lifetime; closing it is the process exit's responsibility.
  *
- * Import is deferred to the factory call so that test files can exercise
- * the SchemaCache class without pulling neo4j-driver into the module graph.
+ * The import is deferred so test files can exercise the SchemaCache class
+ * without pulling neo4j-driver into their module graph.
+ */
+let sharedDriverPromise: Promise<unknown> | null = null;
+
+export async function getSharedDriver(
+  uri: string,
+  user: string,
+  password: string,
+): Promise<unknown> {
+  if (!sharedDriverPromise) {
+    // Clear the cached promise on rejection so a transient failure (e.g. a
+    // slow-to-import neo4j-driver during boot) doesn't wedge every subsequent
+    // call for the process lifetime (review F4).
+    sharedDriverPromise = (async () => {
+      const neo4j = await import("neo4j-driver");
+      return neo4j.default.driver(uri, neo4j.default.auth.basic(user, password));
+    })().catch((err) => {
+      sharedDriverPromise = null;
+      throw err;
+    });
+  }
+  return sharedDriverPromise;
+}
+
+/**
+ * Build a SchemaFetcher over the shared neo4j-driver Driver. Each call
+ * opens a fresh session (cheap, sub-ms) and closes it in finally.
  */
 export async function neo4jSchemaFetcher(
   uri: string,
   user: string,
   password: string,
 ): Promise<SchemaFetcher> {
-  const neo4j = await import("neo4j-driver");
-  const driver = neo4j.default.driver(uri, neo4j.default.auth.basic(user, password));
+  const driver = (await getSharedDriver(uri, user, password)) as {
+    session: () => { run: (q: string) => Promise<{ records: Array<{ get: (k: number) => unknown }> }>; close: () => Promise<void> };
+  };
   const query = async (cypher: string): Promise<string[]> => {
     const session = driver.session();
     try {

package/payload/platform/lib/graph-write/dist/__tests__/audit.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=audit.test.d.ts.map

package/payload/platform/lib/graph-write/dist/__tests__/audit.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/audit.test.ts"],"names":[],"mappings":""}