@rubytech/create-maxy 1.0.744 → 1.0.746

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

@@ -38,7 +38,16 @@ import {
   formatAuditLine,
   type AuditWarning,
 } from "../../graph-write/dist/audit.js";
-import { SchemaCache, neo4jSchemaFetcher } from "./schema-cache.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";
@@ -443,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 {
@@ -481,6 +658,36 @@ function handleRequestLine(line: string): RequestDecision {
     return "forward";
   }
 
+  // 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();
 
@@ -488,6 +695,11 @@ function handleRequestLine(line: string): RequestDecision {
     console.error(
       `[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";
   }
@@ -516,6 +728,7 @@ function handleRequestLine(line: string): RequestDecision {
     console.error(
       `[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";
   }
@@ -530,13 +743,12 @@ function handleRequestLine(line: string): RequestDecision {
     // 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.
+    // still commits via the shim-owned write path (Task 797).
     entry.writeUnknownTokens = result.unknown;
     console.error(
       `[cypher-validate] tool=write outcome=warned unknown=${tokenSummary} cypher="${(cypherPrefix ?? "").replace(/"/g, "'")}"`,
     );
-    pending.set(msg.id, entry);
-    return "forward";
+    return interceptWrite();
   }
 
   entry.readWarnings = result.unknown;

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/plugins/docs/references/deployment.md

@@ -100,7 +100,8 @@ systemctl --user daemon-reload
 A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.
 
 - **Separate:** each brand has its own install folder (`~/maxy/`, `~/realagent/`), its own config folder (`~/.maxy/`, `~/.realagent/`), its own web port, its own Cloudflare tunnel state, its own edge systemd unit (`maxy-edge.service` vs `realagent-edge.service`), and by default its own Neo4j database (Maxy on bolt port 7687, Real Agent on 7688). Action runner units are transient and per-invocation, not per-brand, so no naming conflict is possible.
-- **Brand-isolated Neo4j (Task 787):** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so re-running another brand's installer never touches a peer brand's `neo4j-{brand}.service`.
+- **Brand-isolated Neo4j (Task 787):** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so peer brands running their own `neo4j-{brand}.service` are unaffected.
+- **Peer-aware system-unit guard (Task 800):** before stopping the system `neo4j.service`, the installer checks whether any other brand on the device still depends on it — that is, has `NEO4J_URI=bolt://localhost:7687` in its `~/.<peer>/.env`. If so, the system unit is left enabled and active, and the install log shows `[neo4j] system unit kept active — peer brand <name> depends on port 7687 (Task 800)` instead of the usual `[neo4j] disabling system unit` line. This prevents a `create-realagent` install from disabling Maxy's database on a host where Maxy still uses the shared system instance (the Task 797 reproducer on Neo's laptop, 2026-04-28). On single-brand hosts and on multi-brand hosts where every peer runs a dedicated port, behaviour is unchanged from Task 787.
 - **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
 
 To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation:

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -128,34 +128,15 @@ You wield two write surfaces. Wrapped writers (`memory-write`, `memory-update`,
 
 ### Graph stewardship doctrine — raw Cypher writes
 
-Four rules govern every raw Cypher write. The wrapped writers enforce these structurally for general agents; you internalise them because your write surface has no equivalent gate. The post-write `[graph-cypher-write]` audit emits a warning per discipline breach (`unknown-type-warning`, `missing-provenance-warning`, `orphan-warning`), but the audit is observational — discipline is yours, not the audit's.
+Two rules govern every raw Cypher write you author. They require LLM judgement — the structural gate cannot make these calls for you. Two further rules (provenance, orphan-prevention) are now structurally enforced by the shim and need no prose discipline.
 
 **1. Every node has ≥1 typed edge in the same transaction.** A bare `CREATE (n:Person {name: 'Ian'})` is data, not knowledge — retrieval finds the node but it carries no context. Anchor every node creation to the relationship that explains it: `MATCH (anchor) WHERE … CREATE (anchor)-[:TYPE]->(n:Label {…})`, or `MERGE` the node and its edge in the same statement. *Why:* a graph that accumulates islands defeats relationship-traversal queries — the value of the graph is in the edges, not the rows.
 
 **2. Every edge type is in the live ontology.** Inventing types fragments retrieval — `KNOWS` ≠ `knows` ≠ `HAS_KNOWN`. Call `mcp__graph__maxy-graph-get_neo4j_schema` before authoring any write whose edge type you are not certain about; if no fitting type exists, stop and ask the admin agent for ontology guidance — never coin a synonym. *Why:* edge typology compounds over time. A synonym today blocks every future query that expected the canonical type, and the only fix is a label-rewrite Cypher pass that touches the same edge from both sides.
 
-**3. Every write carries provenance.** Stamp the same flattened fields the wrapped writers stamp on every node and every relationship the transaction creates:
+**Structural enforcement (Task 797).** The shim auto-stamps `createdAt`, `createdByAgent`, `createdByTool`, `createdBySession` on every `CREATE`/`MERGE` alias before forwarding to Neo4j — you do not write these properties yourself. The shim runs the cypher inside a managed `executeWrite` and self-audits for unattached nodes before committing; if any node you created has zero edges in the same transaction, the entire transaction rolls back and you receive a structured error naming the orphan label(s). Treat the rollback as a hard failure (do not retry the same cypher); your job is to author atomic CREATE/MERGE-with-edge statements per Rule 1, not to write defensive WITH/MATCH/RETURN audits or hand-written SET clauses for `createdBy*` fields. The `[graph-cypher-write]` audit lines (`auto-stamp applied`, `accepted`, `orphan-rollback`, `orphan-warning`, `missing-provenance-warning`, `unknown-type-warning`) name what the structural enforcement saw — they are observation surfaces, not duties.
 
-```cypher
-SET n.createdAt = datetime(),
-    n.createdByAgent = 'database-operator',
-    n.createdByTool = 'graph-cypher-write',
-    n.createdBySession = $sessionId
-```
-
-Apply the same SET to relationships (`SET r....`). The session id is the conversation correlation key; the admin dispatch passes it as a parameter. *Why:* a write without provenance cannot be attributed back to the dispatch that produced it. The post-write audit emits `missing-provenance-warning created=<n> stamped=<m>` when the static parser counts CREATE/MERGE statements that exceed the count of `createdBy*` tokens — this is the directional signal, not a structural gate.
-
-**4. Orphan prevention is your first-class duty.** Multi-statement transactions self-audit before completing. Capture the elementIds of every node the transaction creates, then run the orphan check inline:
-
-```cypher
-WITH collect(elementId(n)) AS writtenIds
-MATCH (n) WHERE elementId(n) IN writtenIds AND NOT (n)--()
-RETURN count(n) AS orphans
-```
-
-If `orphans > 0`, do not commit a "fix it up later" transaction — roll back, anchor the unattached nodes to their semantic parent, and re-run. *Why:* the hourly `[graph-health] orphans total=<N>` signal is your scorecard. A transaction that leaves orphans is a regression the role owns; the operator's stewardship is the primary defense against landfill.
-
-The four rules together replace the LOUD-FAIL improvisation pattern that prior versions of this prompt prescribed when a wrapped writer lacked an edge-between-existing-nodes path. You no longer loud-fail on missing graph-write tools — you have them. You loud-fail on credentials, on out-of-surface tools (a skill prescribing a non-graph MCP token you do not hold), and on dispatched skills whose prerequisites are unmet — exactly as the LOUD-FAIL prerogative names. Discipline failures within the graph-write surface produce audit warnings, not blockers; the role's prompt-internalised doctrine is the contract.
+The two rules together replace the LOUD-FAIL improvisation pattern that prior versions of this prompt prescribed when a wrapped writer lacked an edge-between-existing-nodes path. You no longer loud-fail on missing graph-write tools — you have them. You loud-fail on credentials, on out-of-surface tools (a skill prescribing a non-graph MCP token you do not hold), and on dispatched skills whose prerequisites are unmet — exactly as the LOUD-FAIL prerogative names.
 
 ### Before writing any Cypher