@rubytech/create-realagent 1.0.678 → 1.0.681

package/payload/platform/lib/graph-mcp/dist/__tests__/schema-cache.test.js

@@ -0,0 +1,163 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const schema_cache_js_1 = require("../schema-cache.js");
+function makeFetcher(labels, rels, opts = {}) {
+    let called = 0;
+    let currentLabels = labels;
+    let currentRels = rels;
+    return {
+        get calls() {
+            return called;
+        },
+        async labels() {
+            called++;
+            if (opts.failOnce && called === 1)
+                throw new Error("transient");
+            return currentLabels;
+        },
+        async relationshipTypes() {
+            return currentRels;
+        },
+    };
+}
+(0, node_test_1.default)("start() populates the snapshot and sets ready()", async () => {
+    const fetcher = makeFetcher(["Conversation", "Message"], ["PART_OF"]);
+    const emitted = [];
+    const cache = new schema_cache_js_1.SchemaCache(fetcher, {
+        refreshIntervalMs: 0,
+        emit: (l) => emitted.push(l),
+    });
+    strict_1.default.equal(cache.ready(), false);
+    await cache.start();
+    strict_1.default.equal(cache.ready(), true);
+    const snap = cache.snapshot();
+    strict_1.default.ok(snap.labels.has("Conversation"));
+    strict_1.default.ok(snap.labels.has("Message"));
+    strict_1.default.ok(snap.relationshipTypes.has("PART_OF"));
+    strict_1.default.ok(emitted.some((l) => l.includes("[schema-cache] refresh")));
+    cache.stop();
+});
+(0, node_test_1.default)("start() with Neo4j unreachable leaves cache empty and not ready, but does not throw", async () => {
+    const fetcher = {
+        async labels() {
+            throw new Error("ECONNREFUSED");
+        },
+        async relationshipTypes() {
+            throw new Error("ECONNREFUSED");
+        },
+    };
+    const emitted = [];
+    const cache = new schema_cache_js_1.SchemaCache(fetcher, {
+        refreshIntervalMs: 0,
+        emit: (l) => emitted.push(l),
+    });
+    await cache.start();
+    strict_1.default.equal(cache.ready(), false);
+    strict_1.default.equal(cache.snapshot().labels.size, 0);
+    strict_1.default.ok(emitted.some((l) => l.includes("[schema-cache]") && l.includes("failure")), "expected a failure log line");
+    cache.stop();
+});
+(0, node_test_1.default)("refresh() picks up a newly-added relationship type", async () => {
+    let rels = ["PART_OF"];
+    const fetcher = {
+        async labels() {
+            return ["Conversation"];
+        },
+        async relationshipTypes() {
+            return rels;
+        },
+    };
+    const cache = new schema_cache_js_1.SchemaCache(fetcher, { refreshIntervalMs: 0 });
+    await cache.start();
+    strict_1.default.equal(cache.snapshot().relationshipTypes.has("MIGRATED_EDGE"), false);
+    rels = ["PART_OF", "MIGRATED_EDGE"];
+    await cache.refresh("interval");
+    strict_1.default.ok(cache.snapshot().relationshipTypes.has("MIGRATED_EDGE"));
+    cache.stop();
+});
+(0, node_test_1.default)("refresh() preserves last good cache on transient failure", async () => {
+    let fail = false;
+    const fetcher = {
+        async labels() {
+            if (fail)
+                throw new Error("transient");
+            return ["Conversation"];
+        },
+        async relationshipTypes() {
+            if (fail)
+                throw new Error("transient");
+            return ["PART_OF"];
+        },
+    };
+    const cache = new schema_cache_js_1.SchemaCache(fetcher, { refreshIntervalMs: 0 });
+    await cache.start();
+    strict_1.default.equal(cache.ready(), true);
+    fail = true;
+    const ok = await cache.refresh("interval");
+    strict_1.default.equal(ok, false);
+    strict_1.default.equal(cache.ready(), true, "should remain ready after a transient failure");
+    strict_1.default.ok(cache.snapshot().labels.has("Conversation"));
+    cache.stop();
+});
+(0, node_test_1.default)("maybeRebuildOnStaleMiss() triggers refresh when an unknown token has a near match", async () => {
+    let rels = ["PART_OF"];
+    const fetcher = {
+        async labels() {
+            return ["Conversation"];
+        },
+        async relationshipTypes() {
+            return rels;
+        },
+    };
+    const cache = new schema_cache_js_1.SchemaCache(fetcher, {
+        refreshIntervalMs: 0,
+        staleMissDebounceMs: 0,
+    });
+    await cache.start();
+    rels = ["PART_OF", "PART_OFF"];
+    const triggered = await cache.maybeRebuildOnStaleMiss([
+        { token: "PART_OFF", kind: "relationship", nearest: ["PART_OF"], hint: "" },
+    ]);
+    strict_1.default.equal(triggered, true);
+    strict_1.default.ok(cache.snapshot().relationshipTypes.has("PART_OFF"));
+    cache.stop();
+});
+(0, node_test_1.default)("maybeRebuildOnStaleMiss() skips when no near match (likely typo, not migration)", async () => {
+    const fetcher = makeFetcher(["Conversation"], ["PART_OF"]);
+    const cache = new schema_cache_js_1.SchemaCache(fetcher, {
+        refreshIntervalMs: 0,
+        staleMissDebounceMs: 0,
+    });
+    await cache.start();
+    const callsBefore = fetcher.calls;
+    const triggered = await cache.maybeRebuildOnStaleMiss([
+        { token: "COMPLETELY_DIFFERENT", kind: "relationship", nearest: ["PART_OF"], hint: "" },
+    ]);
+    strict_1.default.equal(triggered, false);
+    strict_1.default.equal(fetcher.calls, callsBefore, "no extra fetches when edit distance is far");
+    cache.stop();
+});
+(0, node_test_1.default)("maybeRebuildOnStaleMiss() debounces repeated triggers", async () => {
+    const fetcher = makeFetcher(["Conversation"], ["PART_OF"]);
+    const cache = new schema_cache_js_1.SchemaCache(fetcher, {
+        refreshIntervalMs: 0,
+        staleMissDebounceMs: 5000,
+    });
+    await cache.start();
+    const callsBefore = fetcher.calls;
+    const unknown = [
+        { token: "PART_OFF", kind: "relationship", nearest: ["PART_OF"], hint: "" },
+    ];
+    await cache.maybeRebuildOnStaleMiss(unknown);
+    const afterFirst = fetcher.calls;
+    await cache.maybeRebuildOnStaleMiss(unknown);
+    strict_1.default.equal(fetcher.calls, afterFirst, "second call within debounce should not refetch");
+    strict_1.default.ok(afterFirst > callsBefore, "first call did refetch");
+    cache.stop();
+});
+//# sourceMappingURL=schema-cache.test.js.map

package/payload/platform/lib/graph-mcp/dist/__tests__/schema-cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-cache.test.js","sourceRoot":"","sources":["../../src/__tests__/schema-cache.test.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,38 @@
+/**
+ * Cypher schema validation for the graph-mcp proxy (Task 654).
+ *
+ * Tokenises a cypher string for labels (`:Label`) and relationship types
+ * (`[:REL_TYPE]`, including `[r:TYPE]`, `[:TYPE*1..5]`, `[:A|B]`) and checks
+ * each against a schema snapshot. Unknown tokens are returned with the
+ * Levenshtein-nearest known tokens of the same kind as suggestions.
+ *
+ * Design posture:
+ *   - Defence layer, not a cypher correctness gate. Pass-through on any
+ *     unparseable pattern — Neo4j remains the syntax authority.
+ *   - Empty schema snapshot (cache not ready, or Neo4j unreachable at boot)
+ *     fails OPEN: ok=true, no rejections. The boot-race treatment is a
+ *     deliberate choice — refusing all cypher would wedge the admin agent
+ *     harder than the typo class this layer prevents. The caller emits
+ *     `validated=false` on the existing [graph-query] line so operators
+ *     still see the bypass.
+ *   - String literals are stripped before tokenisation to avoid matching
+ *     `:Foo` inside quoted content (e.g. `WHERE n.note CONTAINS ':Foo'`).
+ */
+export interface SchemaSnapshot {
+    readonly labels: ReadonlySet<string>;
+    readonly relationshipTypes: ReadonlySet<string>;
+}
+export interface UnknownToken {
+    token: string;
+    kind: "label" | "relationship";
+    nearest: string[];
+    hint: string;
+}
+export interface ValidationResult {
+    ok: boolean;
+    unknown: UnknownToken[];
+    labelTokens: string[];
+    edgeTokens: string[];
+}
+export declare function validate(cypher: string, snapshot: SchemaSnapshot): ValidationResult;
+//# sourceMappingURL=cypher-validate.d.ts.map

package/payload/platform/lib/graph-mcp/dist/cypher-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypher-validate.d.ts","sourceRoot":"","sources":["../src/cypher-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACjD;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,GAAG,cAAc,CAAC;IAC/B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAkFD,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,GACvB,gBAAgB,CAiClB"}

package/payload/platform/lib/graph-mcp/dist/cypher-validate.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Cypher schema validation for the graph-mcp proxy (Task 654).
+ *
+ * Tokenises a cypher string for labels (`:Label`) and relationship types
+ * (`[:REL_TYPE]`, including `[r:TYPE]`, `[:TYPE*1..5]`, `[:A|B]`) and checks
+ * each against a schema snapshot. Unknown tokens are returned with the
+ * Levenshtein-nearest known tokens of the same kind as suggestions.
+ *
+ * Design posture:
+ *   - Defence layer, not a cypher correctness gate. Pass-through on any
+ *     unparseable pattern — Neo4j remains the syntax authority.
+ *   - Empty schema snapshot (cache not ready, or Neo4j unreachable at boot)
+ *     fails OPEN: ok=true, no rejections. The boot-race treatment is a
+ *     deliberate choice — refusing all cypher would wedge the admin agent
+ *     harder than the typo class this layer prevents. The caller emits
+ *     `validated=false` on the existing [graph-query] line so operators
+ *     still see the bypass.
+ *   - String literals are stripped before tokenisation to avoid matching
+ *     `:Foo` inside quoted content (e.g. `WHERE n.note CONTAINS ':Foo'`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validate = validate;
+// Bracket content containing a type reference. Examples this matches:
+//   [:PART_OF]
+//   [r:PART_OF]
+//   [:PART_OF*1..5]
+//   [r:PART_OF*]
+//   [:A|B]
+// The captured group is the TYPE(|TYPE)* alternation; the consumer splits it.
+const EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[^\]]*?\]/g;
+// Label reference in a node pattern. Applied to a remainder string that has
+// already had edge-bracket substrings stripped, so there is no overlap with
+// the edge pattern. The [A-Z] anchor excludes lowercase map keys.
+const LABEL_PATTERN = /:([A-Z][A-Za-z0-9_]*)/g;
+function stripStringLiterals(cypher) {
+    // 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).
+    return cypher.replace(/'[^']*'|"[^"]*"/g, '""');
+}
+function extractTokens(cypher) {
+    const cleaned = stripStringLiterals(cypher);
+    const edges = new Set();
+    let match;
+    const edgePattern = new RegExp(EDGE_PATTERN.source, EDGE_PATTERN.flags);
+    while ((match = edgePattern.exec(cleaned)) !== null) {
+        for (const type of match[1].split("|")) {
+            const clean = type.trim();
+            if (clean)
+                edges.add(clean);
+        }
+    }
+    const remainder = cleaned.replace(edgePattern, "");
+    const labels = new Set();
+    const labelPattern = new RegExp(LABEL_PATTERN.source, LABEL_PATTERN.flags);
+    while ((match = labelPattern.exec(remainder)) !== null) {
+        labels.add(match[1]);
+    }
+    return { labels, edges };
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let prev = new Array(b.length + 1);
+    let curr = new Array(b.length + 1);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[b.length];
+}
+function nearestMatches(token, known, limit = 3) {
+    if (known.size === 0)
+        return [];
+    const scored = [];
+    for (const k of known)
+        scored.push([k, levenshtein(token, k)]);
+    scored.sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0]));
+    return scored.slice(0, limit).map(([k]) => k);
+}
+function hintFor(token, kind, nearest) {
+    const didYouMean = nearest.length > 0 ? `Did you mean :${nearest[0]}? ` : "";
+    return `${didYouMean}Unknown ${kind} '${token}' — not in the current Neo4j schema. See .docs/neo4j.md for the canonical taxonomy.`;
+}
+function validate(cypher, snapshot) {
+    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.
+    if (snapshot.labels.size === 0 && snapshot.relationshipTypes.size === 0) {
+        return {
+            ok: true,
+            unknown: [],
+            labelTokens: [...labels],
+            edgeTokens: [...edges],
+        };
+    }
+    const unknown = [];
+    for (const token of labels) {
+        if (!snapshot.labels.has(token)) {
+            const nearest = nearestMatches(token, snapshot.labels);
+            unknown.push({ token, kind: "label", nearest, hint: hintFor(token, "label", nearest) });
+        }
+    }
+    for (const token of edges) {
+        if (!snapshot.relationshipTypes.has(token)) {
+            const nearest = nearestMatches(token, snapshot.relationshipTypes);
+            unknown.push({ token, kind: "relationship", nearest, hint: hintFor(token, "relationship", nearest) });
+        }
+    }
+    return {
+        ok: unknown.length === 0,
+        unknown,
+        labelTokens: [...labels],
+        edgeTokens: [...edges],
+    };
+}
+//# sourceMappingURL=cypher-validate.js.map

package/payload/platform/lib/graph-mcp/dist/cypher-validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cypher-validate.js","sourceRoot":"","sources":["../src/cypher-validate.ts"],"names":[],"mappings":"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"}

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

@@ -29,6 +29,8 @@ const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_string_decoder_1 = require("node:string_decoder");
 const index_js_1 = require("../../mcp-stderr-tee/dist/index.js");
+const cypher_validate_js_1 = require("./cypher-validate.js");
+const schema_cache_js_1 = require("./schema-cache.js");
 const SERVER_NAME = "graph";
 const UPSTREAM_PACKAGE = "mcp-neo4j-cypher@0.6.0";
 (0, index_js_1.initStderrTee)(SERVER_NAME);
@@ -161,6 +163,37 @@ const childEnv = {
 };
 console.error(`[graph-mcp] boot brand=${brand} uri=${neo4jUri} user=${neo4jUser} ` +
     `namespace=${namespace} readOnly=${readOnly} tokenLimit=${responseTokenLimit}`);
+// Task 654 — async schema cache. The validator fails OPEN until the first
+// refresh resolves; all cypher calls during that window are forwarded
+// unvalidated and the existing [graph-query] line gains `validated=false`
+// so operators see the bypass. One Neo4j driver is shared across refreshes;
+// loaded lazily so test harnesses can exercise SchemaCache without pulling
+// neo4j-driver into the module graph.
+// neo4jUri is narrowed to `string` by the guard throw above, but the narrow
+// doesn't flow into the closure below. Pin it to a local const whose type
+// is `string` by construction.
+const resolvedNeo4jUri = neo4jUri;
+let schemaFetcherReady = null;
+function getSchemaFetcher() {
+    if (!schemaFetcherReady) {
+        schemaFetcherReady = (0, schema_cache_js_1.neo4jSchemaFetcher)(resolvedNeo4jUri, neo4jUser, neo4jPassword);
+    }
+    return schemaFetcherReady;
+}
+const schemaCache = new schema_cache_js_1.SchemaCache({
+    async labels() {
+        const f = await getSchemaFetcher();
+        return f.labels();
+    },
+    async relationshipTypes() {
+        const f = await getSchemaFetcher();
+        return f.relationshipTypes();
+    },
+});
+void schemaCache.start().catch((err) => {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[schema-cache] start failed error="${msg.replace(/"/g, "'")}"`);
+});
 const uvx = resolveUvxPath();
 if (!uvx.path) {
     syncEmit(`uvx unresolvable — checked env=${uvx.envChecked} home-local=${uvx.homeLocalChecked} which=${uvx.whichChecked}`);
@@ -198,11 +231,16 @@ function stripNamespace(toolName) {
     const prefix = `${namespace}_`;
     return toolName.startsWith(prefix) ? toolName.slice(prefix.length) : toolName;
 }
-function extractCypher(args) {
+const READ_CYPHER_TOOL = "read_neo4j_cypher";
+const WRITE_CYPHER_TOOL = "write_neo4j_cypher";
+function extractCypherFull(args) {
     if (!args)
         return null;
     const q = args["query"] ?? args["cypher"];
-    return typeof q === "string" ? truncate(q.replace(/\s+/g, " ").trim(), 80) : null;
+    return typeof q === "string" ? q : null;
+}
+function truncateForLog(cypher) {
+    return truncate(cypher.replace(/\s+/g, " ").trim(), 80);
 }
 function countRows(result) {
     if (!result?.content || !Array.isArray(result.content))
@@ -213,69 +251,187 @@ function countRows(result) {
         return rowsMatch[1];
     return String(result.content.length);
 }
-function onRequestLine(line) {
+/**
+ * Render the admin-facing rejection or warnings text. Plain prose so the
+ * agent's Tool Failure Discipline reads it the same way it reads any tool
+ * error — no special-case structured JSON parser required.
+ */
+function renderUnknownTokens(unknown, mode) {
+    const heading = mode === "rejected"
+        ? "schema-validation rejected — cypher NOT executed"
+        : "schema-validation warning — cypher executed but referenced unknown tokens";
+    const lines = unknown.map((u) => {
+        const nearest = u.nearest.length > 0 ? ` nearest=[${u.nearest.join(", ")}]` : "";
+        return `  - ${u.kind} '${u.token}':${nearest} — ${u.hint}`;
+    });
+    return `${heading}\n${lines.join("\n")}`;
+}
+function synthesiseRejection(id, unknown) {
+    const text = `${renderUnknownTokens(unknown, "rejected")}\n\nFix the token names, or if the schema has just changed, invoke ${namespace}_get_neo4j_schema to refresh your view.`;
+    const envelope = {
+        jsonrpc: "2.0",
+        id,
+        result: {
+            content: [{ type: "text", text }],
+            isError: true,
+        },
+    };
+    return JSON.stringify(envelope);
+}
+function wrapReadWarnings(msg, warnings) {
+    const warningText = `${renderUnknownTokens(warnings, "warning")}\n\n--- results below (executed despite unknown tokens) ---\n`;
+    const original = msg.result?.content ?? [];
+    const wrapped = {
+        ...msg,
+        result: {
+            ...(msg.result ?? {}),
+            content: [{ type: "text", text: warningText }, ...original],
+        },
+    };
+    return JSON.stringify(wrapped);
+}
+function handleRequestLine(line) {
+    let msg;
     try {
-        const msg = JSON.parse(line);
-        if (msg.method === "tools/call" && msg.id !== undefined) {
-            pending.set(msg.id, {
-                method: stripNamespace(msg.params?.name),
-                cypherPrefix: extractCypher(msg.params?.arguments),
-                startMs: Date.now(),
-            });
-        }
+        msg = JSON.parse(line);
     }
     catch {
-        // Non-JSON / partial line — forward untouched, don't log.
+        return "forward";
+    }
+    if (msg.method !== "tools/call" || msg.id === undefined)
+        return "forward";
+    const methodName = stripNamespace(msg.params?.name);
+    const cypherFull = extractCypherFull(msg.params?.arguments);
+    const cypherPrefix = cypherFull ? truncateForLog(cypherFull) : null;
+    const isCypherCall = methodName === READ_CYPHER_TOOL || methodName === WRITE_CYPHER_TOOL;
+    const entry = {
+        method: methodName,
+        cypherPrefix,
+        startMs: Date.now(),
+        validated: false,
+        readWarnings: [],
+    };
+    if (!isCypherCall || !cypherFull) {
+        pending.set(msg.id, entry);
+        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, "'")}"`);
+        pending.set(msg.id, entry);
+        return "forward";
+    }
+    const result = (0, cypher_validate_js_1.validate)(cypherFull, snapshot);
+    entry.validated = true;
+    if (result.ok) {
+        console.error(`[cypher-validate] tool=${isWrite ? "write" : "read"} outcome=accepted labels=${result.labelTokens.length} relationships=${result.edgeTokens.length}`);
+        pending.set(msg.id, entry);
+        return "forward";
+    }
+    void schemaCache.maybeRebuildOnStaleMiss(result.unknown);
+    const tokenSummary = result.unknown
+        .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`);
+        console.error(`[graph-query] op=${methodName} brand=${brand} port=${neo4jPort} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}" rejected=true validated=true ms=${Date.now() - entry.startMs}`);
+        return "intercepted";
     }
+    entry.readWarnings = result.unknown;
+    console.error(`[cypher-validate] tool=read outcome=warned unknown=${tokenSummary} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`);
+    pending.set(msg.id, entry);
+    return "forward";
 }
-function onResponseLine(line) {
+function handleResponseLine(line) {
+    let msg;
     try {
-        const msg = JSON.parse(line);
-        if (msg.id === undefined || !pending.has(msg.id))
-            return;
-        const p = pending.get(msg.id);
-        pending.delete(msg.id);
-        const elapsed = Date.now() - p.startMs;
-        const cypherField = p.cypherPrefix ? `cypher="${p.cypherPrefix.replace(/"/g, "'")}"` : "";
-        if (msg.error) {
-            const errText = (msg.error.message ?? JSON.stringify(msg.error)).replace(/"/g, "'");
-            console.error(`[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} error="${errText}" ms=${elapsed}`);
-        }
-        else {
-            const rows = countRows(msg.result);
-            console.error(`[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} rows=${rows} ms=${elapsed}`);
-        }
+        msg = JSON.parse(line);
     }
     catch {
-        // Non-JSON — forward untouched.
+        return null;
+    }
+    if (msg.id === undefined || !pending.has(msg.id))
+        return null;
+    const p = pending.get(msg.id);
+    pending.delete(msg.id);
+    const elapsed = Date.now() - p.startMs;
+    const cypherField = p.cypherPrefix ? `cypher="${p.cypherPrefix.replace(/"/g, "'")}"` : "";
+    const validatedField = `validated=${p.validated}`;
+    if (msg.error) {
+        const errText = (msg.error.message ?? JSON.stringify(msg.error)).replace(/"/g, "'");
+        console.error(`[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} error="${errText}" ${validatedField} ms=${elapsed}`);
+        return null;
+    }
+    const rows = countRows(msg.result);
+    const warnedField = p.readWarnings.length > 0 ? ` warned=${p.readWarnings.length}` : "";
+    console.error(`[graph-query] op=${p.method} brand=${brand} port=${neo4jPort} ${cypherField} rows=${rows} ${validatedField}${warnedField} ms=${elapsed}`);
+    if (p.readWarnings.length > 0) {
+        try {
+            return wrapReadWarnings(msg, p.readWarnings);
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            console.error(`[cypher-validate] warning-wrap failed op=${p.method} error="${errMsg.replace(/"/g, "'")}" — forwarding response unwrapped`);
+            return null;
+        }
     }
+    return null;
 }
-function makeLineSplitter(onLine) {
+/**
+ * Per-stream buffering splitter. Yields complete lines (without trailing \n)
+ * as they accumulate; leaves any partial tail in the buffer until more bytes
+ * arrive. Unlike the pre-Task-652 splitter, this one lets the caller decide
+ * per-line whether to forward or intercept — the original splitter was
+ * fire-and-forget and the raw chunk was forwarded unconditionally alongside,
+ * which ruled out interception.
+ */
+function makeLineBuffer() {
     const decoder = new node_string_decoder_1.StringDecoder("utf8");
     let buf = "";
-    return (chunk) => {
-        buf += decoder.write(chunk);
-        let idx;
-        while ((idx = buf.indexOf("\n")) !== -1) {
-            const line = buf.slice(0, idx);
-            buf = buf.slice(idx + 1);
-            if (line.length > 0)
-                onLine(line);
-        }
+    return {
+        push(chunk) {
+            buf += decoder.write(chunk);
+            const out = [];
+            let idx;
+            while ((idx = buf.indexOf("\n")) !== -1) {
+                out.push(buf.slice(0, idx));
+                buf = buf.slice(idx + 1);
+            }
+            return out;
+        },
     };
 }
-const splitRequest = makeLineSplitter(onRequestLine);
+const requestBuffer = makeLineBuffer();
 process.stdin.on("data", (chunk) => {
-    splitRequest(chunk);
-    child.stdin.write(chunk);
+    for (const line of requestBuffer.push(chunk)) {
+        if (line.length === 0) {
+            child.stdin.write("\n");
+            continue;
+        }
+        const decision = handleRequestLine(line);
+        if (decision === "forward") {
+            child.stdin.write(`${line}\n`);
+        }
+        // "intercepted" — synthesised response already written to stdout.
+    }
 });
 process.stdin.on("end", () => {
     child.stdin.end();
 });
-const splitResponse = makeLineSplitter(onResponseLine);
+const responseBuffer = makeLineBuffer();
 child.stdout.on("data", (chunk) => {
-    splitResponse(chunk);
-    process.stdout.write(chunk);
+    for (const line of responseBuffer.push(chunk)) {
+        if (line.length === 0) {
+            process.stdout.write("\n");
+            continue;
+        }
+        const rewritten = handleResponseLine(line);
+        process.stdout.write(`${rewritten ?? line}\n`);
+    }
 });
 child.stdout.on("end", () => {
     process.stdout.end();