@rubytech/create-maxy 1.0.743 → 1.0.744

package/payload/platform/lib/graph-mcp/src/__tests__/cypher-validate-write.test.ts

@@ -0,0 +1,150 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { validate, type SchemaSnapshot } from "../cypher-validate.js";
+
+const snapshot: SchemaSnapshot = {
+  labels: new Set(["Person", "Organization", "Task", "KnowledgeDocument"]),
+  relationshipTypes: new Set(["KNOWS", "PARTICIPANT", "REFERENCES", "MENTIONS", "PART_OF"]),
+};
+
+test("write mode allows CREATE node + relationship statement", () => {
+  const result = validate(
+    "MATCH (a:Person), (b:Organization) WHERE a.name = $a AND b.name = $b CREATE (a)-[:KNOWS]->(b)",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.equal(result.ok, true, "expected valid write");
+  assert.deepEqual(result.unknown, []);
+  assert.deepEqual(result.forbidden, []);
+});
+
+test("write mode allows MERGE with SET clause", () => {
+  const result = validate(
+    "MATCH (a:Person {name: $name}) MERGE (a)-[r:KNOWS]->(b:Person {name: $other}) SET r.createdAt = datetime()",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.equal(result.ok, true);
+});
+
+test("write mode allows DETACH DELETE", () => {
+  const result = validate(
+    "MATCH (n:Person) WHERE n.archived = true DETACH DELETE n",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.equal(result.ok, true);
+});
+
+test("write mode allows REMOVE label + SET label (re-label)", () => {
+  // Allow renaming labels — the new label is unknown to the schema until the
+  // write commits, but the validator must not block legitimate normalisation.
+  const result = validate(
+    "MATCH (n:Person) WHERE n.legacy = true REMOVE n:Person SET n:LegacyPerson",
+    snapshot,
+    { mode: "write" },
+  );
+  // LegacyPerson is unknown — fail-soft for write mode (audit emits warning, not reject).
+  // The token check is shared with read-mode; the write mode adds DDL/admin reject layer.
+  // For this test we accept the write-mode-specific outcome: no forbidden patterns.
+  assert.deepEqual(result.forbidden, []);
+});
+
+test("write mode allows CALL apoc.refactor.mergeNodes", () => {
+  const result = validate(
+    "MATCH (a:Person), (b:Person) WHERE a.email = b.email AND id(a) < id(b) WITH a, b CALL apoc.refactor.mergeNodes([a, b]) YIELD node RETURN node",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.deepEqual(result.forbidden, []);
+});
+
+test("write mode REJECTS DROP DATABASE", () => {
+  const result = validate("DROP DATABASE neo4j", snapshot, { mode: "write" });
+  assert.equal(result.ok, false);
+  assert.equal(result.forbidden.length, 1);
+  assert.equal(result.forbidden[0].kind, "drop-database");
+});
+
+test("write mode REJECTS CREATE INDEX", () => {
+  const result = validate(
+    "CREATE INDEX person_name_idx FOR (n:Person) ON (n.name)",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.equal(result.ok, false);
+  const f = result.forbidden.find((x) => x.kind === "create-index");
+  assert.ok(f, "expected create-index forbidden");
+});
+
+test("write mode REJECTS CREATE CONSTRAINT", () => {
+  const result = validate(
+    "CREATE CONSTRAINT person_email_unique FOR (n:Person) REQUIRE n.email IS UNIQUE",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.equal(result.ok, false);
+  const f = result.forbidden.find((x) => x.kind === "create-constraint");
+  assert.ok(f);
+});
+
+test("write mode REJECTS CALL dbms.security.*", () => {
+  const result = validate(
+    "CALL dbms.security.createUser('attacker', 'pwd', false)",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.equal(result.ok, false);
+  const f = result.forbidden.find((x) => x.kind === "call-dbms");
+  assert.ok(f);
+});
+
+test("write mode REJECTS CALL db.create*", () => {
+  const result = validate(
+    "CALL db.createLabel('Foo')",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.equal(result.ok, false);
+  const f = result.forbidden.find((x) => x.kind === "call-db-create");
+  assert.ok(f);
+});
+
+test("write mode allows CALL db.labels (read-only db.* call)", () => {
+  // db.labels is a read primitive — not a create/drop. Validator only
+  // forbids db.create* family; CALL db.labels remains allowed.
+  const result = validate("CALL db.labels()", snapshot, { mode: "write" });
+  assert.deepEqual(result.forbidden, []);
+});
+
+test("read mode does NOT apply forbidden checks (DDL pattern in MATCH still allowed)", () => {
+  // String literals containing forbidden tokens never trip — DDL forbidden check
+  // is mode-gated. Read-mode WHERE clauses comparing on a string with the
+  // word DROP must not reject.
+  const result = validate(
+    "MATCH (n:Person) WHERE n.bio CONTAINS 'DROP DATABASE' RETURN n",
+    snapshot,
+    { mode: "read" },
+  );
+  assert.deepEqual(result.forbidden, []);
+  assert.equal(result.ok, true);
+});
+
+test("write mode strips string literals before forbidden check", () => {
+  // The forbidden check must use stripStringLiterals so a string property
+  // value like 'DROP DATABASE archive' does not trip the rejection.
+  const result = validate(
+    "MATCH (n:Person) WHERE n.bio CONTAINS 'DROP DATABASE' SET n.flagged = true",
+    snapshot,
+    { mode: "write" },
+  );
+  assert.deepEqual(result.forbidden, [], "string-literal content must not trip DDL check");
+});
+
+test("default mode is read (backward compatibility)", () => {
+  // Existing call sites pass no mode option — must remain read-mode behavior.
+  const result = validate("MATCH (n:Person) RETURN n", snapshot);
+  assert.equal(result.ok, true);
+  assert.equal(Array.isArray(result.forbidden), true);
+  assert.equal(result.forbidden.length, 0);
+});

package/payload/platform/lib/graph-mcp/src/cypher-validate.ts

@@ -31,13 +31,75 @@ export interface UnknownToken {
   hint: string;
 }
 
+export type ForbiddenKind =
+  | "drop-database"
+  | "create-index"
+  | "create-constraint"
+  | "call-dbms"
+  | "call-db-create";
+
+export interface ForbiddenPattern {
+  kind: ForbiddenKind;
+  match: string;
+  hint: string;
+}
+
 export interface ValidationResult {
   ok: boolean;
   unknown: UnknownToken[];
+  forbidden: ForbiddenPattern[];
   labelTokens: string[];
   edgeTokens: string[];
 }
 
+export interface ValidateOptions {
+  /** "read" (default) skips DDL/admin forbidden checks. "write" applies them. */
+  mode?: "read" | "write";
+}
+
+// DDL / admin patterns that the database-operator's raw write surface must
+// reject. The graph MCP shim is the only enforcement point — Neo4j Community
+// has no per-tool ACL, so the shim filters by syntactic shape before
+// forwarding the JSON-RPC line to the upstream cypher driver. Each pattern
+// is applied to a string-literal-stripped cypher body so that prose inside
+// quoted strings cannot trip a false positive.
+//
+// CALL apoc.* is intentionally NOT forbidden — apoc.refactor.mergeNodes is
+// the documented dedup primitive. CALL db.labels() and other read-only db.*
+// calls are allowed; only db.create* (createLabel, createProperty,
+// createRelationshipType) is forbidden because those are schema-mutating.
+const FORBIDDEN_PATTERNS: ReadonlyArray<{
+  kind: ForbiddenKind;
+  pattern: RegExp;
+  hint: string;
+}> = [
+  {
+    kind: "drop-database",
+    pattern: /\bDROP\s+(?:DATABASE|ALIAS|USER|ROLE)\b/i,
+    hint: "DROP DATABASE/USER/ROLE/ALIAS is admin DDL — not permitted on the operator surface.",
+  },
+  {
+    kind: "create-index",
+    pattern: /\bCREATE\s+(?:OR\s+REPLACE\s+)?(?:RANGE\s+|TEXT\s+|POINT\s+|LOOKUP\s+|FULLTEXT\s+|BTREE\s+|VECTOR\s+)?INDEX\b/i,
+    hint: "Index DDL is admin-owned (seed-neo4j.sh applies indexes). Not permitted on the operator surface.",
+  },
+  {
+    kind: "create-constraint",
+    pattern: /\bCREATE\s+(?:OR\s+REPLACE\s+)?CONSTRAINT\b/i,
+    hint: "Constraint DDL is admin-owned (seed-neo4j.sh applies constraints). Not permitted on the operator surface.",
+  },
+  {
+    kind: "call-dbms",
+    pattern: /\bCALL\s+dbms\./i,
+    hint: "CALL dbms.* is admin/security surface. Not permitted on the operator surface.",
+  },
+  {
+    kind: "call-db-create",
+    pattern: /\bCALL\s+db\.create/i,
+    hint: "CALL db.create* mutates schema (label/property/type registration). Not permitted on the operator surface.",
+  },
+];
+
 // Bracket content containing a type reference. Examples this matches:
 //   [:PART_OF]
 //   [r:PART_OF]
@@ -52,7 +114,10 @@ const EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[
 // the edge pattern. The [A-Z] anchor excludes lowercase map keys.
 const LABEL_PATTERN = /:([A-Z][A-Za-z0-9_]*)/g;
 
-function stripStringLiterals(cypher: string): string {
+// Exported so the post-write audit (graph-write/audit.ts) can reuse the same
+// literal-stripping pass before its own static parsing — avoids duplicate
+// false-positive treatment across the two surfaces.
+export function stripStringLiterals(cypher: string): string {
   // Replace single- and double-quoted literals with empty quotes. Preserves
   // positional structure without retaining content that could match the
   // label regex (e.g. ':SomeLabel' inside a string).
@@ -118,19 +183,40 @@ function hintFor(
   return `${didYouMean}Unknown ${kind} '${token}' — not in the current Neo4j schema. See .docs/neo4j.md for the canonical taxonomy.`;
 }
 
+function detectForbidden(cypher: string): ForbiddenPattern[] {
+  // Strip literals so a property value like 'CREATE INDEX archive' cannot
+  // trip a false rejection. The shared `stripStringLiterals` keeps this
+  // treatment uniform with token extraction and audit static parsing.
+  const cleaned = stripStringLiterals(cypher);
+  const out: ForbiddenPattern[] = [];
+  for (const { kind, pattern, hint } of FORBIDDEN_PATTERNS) {
+    const found = cleaned.match(pattern);
+    if (found) {
+      out.push({ kind, match: found[0], hint });
+    }
+  }
+  return out;
+}
+
 export function validate(
   cypher: string,
   snapshot: SchemaSnapshot,
+  options: ValidateOptions = {},
 ): ValidationResult {
+  const mode = options.mode ?? "read";
+  const forbidden = mode === "write" ? detectForbidden(cypher) : [];
   const { labels, edges } = extractTokens(cypher);
   // Fail-open when the snapshot is empty. An empty snapshot means "schema
   // cache not loaded" (boot race, Neo4j unreachable). Rejecting every token
   // would wedge the admin agent; letting it through preserves the observable
   // `validated=false` signal on the existing [graph-query] line.
+  // Forbidden DDL/admin patterns still apply — those are syntactic, not
+  // schema-derived.
   if (snapshot.labels.size === 0 && snapshot.relationshipTypes.size === 0) {
     return {
-      ok: true,
+      ok: forbidden.length === 0,
       unknown: [],
+      forbidden,
       labelTokens: [...labels],
       edgeTokens: [...edges],
     };
@@ -148,9 +234,15 @@ export function validate(
       unknown.push({ token, kind: "relationship", nearest, hint: hintFor(token, "relationship", nearest) });
     }
   }
+  // Write-mode caller treats `unknown` as a soft warning (audit), not a
+  // hard reject — operators legitimately introduce new labels via REMOVE
+  // n:Old SET n:New. Read-mode preserves prior behaviour: any unknown
+  // → ok=false.
+  const tokensOk = mode === "write" ? true : unknown.length === 0;
   return {
-    ok: unknown.length === 0,
+    ok: tokensOk && forbidden.length === 0,
     unknown,
+    forbidden,
     labelTokens: [...labels],
     edgeTokens: [...edges],
   };

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

@@ -28,7 +28,16 @@ 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 {
+  validate as validateCypher,
+  type ForbiddenPattern,
+  type UnknownToken,
+} from "./cypher-validate.js";
+import {
+  auditCypherWrite,
+  formatAuditLine,
+  type AuditWarning,
+} from "../../graph-write/dist/audit.js";
 import { SchemaCache, neo4jSchemaFetcher } from "./schema-cache.js";
 
 const SERVER_NAME = "graph";
@@ -162,7 +171,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 +267,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 +326,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 +403,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 ?? [];
@@ -369,13 +459,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,24 +481,40 @@ function handleRequestLine(line: string): RequestDecision {
     return "forward";
   }
 
-  const isWrite = methodName === WRITE_CYPHER_TOOL;
   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, "'")}"`,
     );
     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}`,
     );
     pending.set(msg.id, entry);
     return "forward";
@@ -411,16 +525,18 @@ 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
+    // forwards to upstream and commits.
+    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";
+    pending.set(msg.id, entry);
+    return "forward";
   }
 
   entry.readWarnings = result.unknown;
@@ -456,6 +572,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-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":""}