@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/lib/graph-write/src/__tests__/action-provenance-gate.test.ts

@@ -0,0 +1,279 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  ACTION_PROVENANCE_LABELS,
+  writeNodeWithEdges,
+  type GraphRelationship,
+} from "../index.js";
+
+// writeNodeWithEdges now rejects writes whose accountId does not
+// match the spawning process's ACCOUNT_ID. These provenance-gate tests
+// predate that gate; they pass a literal `expectedAccountId` so they
+// exercise only the provenance gate they were written to test.
+const TEST_ACCOUNT_ID = "12345678-9abc-def0-1234-56789abcdef0";
+
+// Stub session/tx — captures Cypher calls and returns canned results.
+interface StubTx {
+  run(cypher: string, params?: Record<string, unknown>): Promise<{
+    records: { get(field: string): unknown }[];
+    summary?: { counters: { updates(): { relationshipsCreated: number } } };
+  }>;
+}
+
+function makeStubSession(opts: {
+  preCheckLabelsByTarget: Map<string, string[]>;
+  edgesCreatedPerCall?: number;
+}) {
+  const calls: { cypher: string; params: Record<string, unknown> }[] = [];
+  const tx: StubTx = {
+    async run(cypher: string, params: Record<string, unknown> = {}) {
+      calls.push({ cypher, params });
+      if (cypher.includes("RETURN elementId(t) AS id, labels(t) AS labels")) {
+        const ids = (params.ids as string[]) ?? [];
+        const records = ids
+          .filter((id) => opts.preCheckLabelsByTarget.has(id))
+          .map((id) => ({
+            get(field: string) {
+              if (field === "id") return id;
+              if (field === "labels") return opts.preCheckLabelsByTarget.get(id) ?? [];
+              throw new Error(`unknown field ${field}`);
+            },
+          }));
+        return { records };
+      }
+      if (cypher.includes("CREATE (n:")) {
+        return {
+          records: [
+            {
+              get(field: string) {
+                if (field === "nodeId") return "new-element-id";
+                if (field === "nodeLabels") return ["Person"];
+                throw new Error(`unknown field ${field}`);
+              },
+            },
+          ],
+        };
+      }
+      if (cypher.includes("CREATE (a)-[") || cypher.includes("CREATE (b)-[")) {
+        return {
+          records: [],
+          summary: {
+            counters: {
+              updates() {
+                return { relationshipsCreated: opts.edgesCreatedPerCall ?? 1 };
+              },
+            },
+          },
+        };
+      }
+      return { records: [] };
+    },
+  };
+  const session = {
+    async executeWrite<T>(work: (tx: StubTx) => Promise<T>): Promise<T> {
+      return await work(tx);
+    },
+  };
+  return { session, calls };
+}
+
+test("ACTION_PROVENANCE_LABELS includes the documented set", () => {
+  for (const label of [
+    "Person",
+    "UserProfile",
+    "AdminUser",
+    "Organization",
+    "LocalBusiness",
+    "CloudflareTunnel",
+    "CloudflareHostname",
+  ]) {
+    assert.ok(
+      ACTION_PROVENANCE_LABELS.has(label),
+      `${label} should be in ACTION_PROVENANCE_LABELS`,
+    );
+  }
+});
+
+// Task 580 relaxed missing-provenance from a hard reject to a soft warn.
+// The write now proceeds; a single structured stderr line carries the labels
+// and agent so operators can quantify how often the gap fires.
+test("writeNodeWithEdges accepts :Person write missing any inbound PRODUCED edge and emits a warn line", async () => {
+  const { session } = makeStubSession({
+    preCheckLabelsByTarget: new Map([["other-target", ["LocalBusiness"]]]),
+  });
+  const relationships: GraphRelationship[] = [
+    // No inbound PRODUCED at all — neither Task nor Conversation nor Message.
+    { type: "PART_OF", direction: "outgoing", targetNodeId: "other-target" },
+  ];
+  const captured: string[] = [];
+  const originalWrite = process.stderr.write.bind(process.stderr);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  process.stderr.write = ((chunk: any) => {
+    captured.push(typeof chunk === "string" ? chunk : String(chunk));
+    return true;
+  }) as typeof process.stderr.write;
+  try {
+    const res = await writeNodeWithEdges({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      session: session as any,
+      labels: ["Person"],
+      props: { accountId: TEST_ACCOUNT_ID },
+      relationships,
+      createdBy: { agent: "maxy-admin", session: "sess-1", tool: "memory-write" },
+      expectedAccountId: TEST_ACCOUNT_ID,
+    });
+    assert.equal(res.edgesCreated, 1);
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+  const warnLine = captured.find((l) => l.includes("[graph-write] warn reason=missing-provenance"));
+  assert.ok(warnLine, `expected warn line; captured=${JSON.stringify(captured)}`);
+  assert.match(warnLine!, /labels=Person/);
+  assert.match(warnLine!, /agent=maxy-admin/);
+});
+
+test("writeNodeWithEdges accepts :Person write with PRODUCED-from-Task edge", async () => {
+  const { session } = makeStubSession({
+    preCheckLabelsByTarget: new Map([
+      ["task-id", ["Task"]],
+    ]),
+  });
+  const relationships: GraphRelationship[] = [
+    { type: "PRODUCED", direction: "incoming", targetNodeId: "task-id" },
+  ];
+  const res = await writeNodeWithEdges({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    session: session as any,
+    labels: ["Person"],
+    props: { accountId: TEST_ACCOUNT_ID },
+    relationships,
+    createdBy: { agent: "maxy-admin", session: "sess-1", tool: "memory-write" },
+    expectedAccountId: TEST_ACCOUNT_ID,
+  });
+  assert.equal(res.edgesCreated, 1);
+});
+
+test("writeNodeWithEdges accepts :Person write with no Task edge when agent='system' (bootstrap exemption)", async () => {
+  const { session } = makeStubSession({
+    preCheckLabelsByTarget: new Map([["admin-user-id", ["AdminUser"]]]),
+  });
+  const relationships: GraphRelationship[] = [
+    { type: "OWNS", direction: "incoming", targetNodeId: "admin-user-id" },
+  ];
+  const res = await writeNodeWithEdges({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    session: session as any,
+    labels: ["Person"],
+    props: { accountId: TEST_ACCOUNT_ID },
+    relationships,
+    createdBy: { agent: "system", source: "writeAdminUserAndPerson" },
+    expectedAccountId: TEST_ACCOUNT_ID,
+  });
+  assert.equal(res.edgesCreated, 1);
+});
+
+// gate widened to accept:Conversation provenance for direct
+// admin asks. The wrapper auto-injects the inbound PRODUCED edge from the
+// active :AdminConversation via SESSION_NODE_ID.
+test("writeNodeWithEdges accepts :Person write with PRODUCED-from-Conversation edge", async () => {
+  const { session } = makeStubSession({
+    preCheckLabelsByTarget: new Map([
+      // AdminConversation carries the parent :Conversation label too.
+      ["conv-id", ["Conversation", "AdminConversation"]],
+    ]),
+  });
+  const relationships: GraphRelationship[] = [
+    { type: "PRODUCED", direction: "incoming", targetNodeId: "conv-id" },
+  ];
+  const res = await writeNodeWithEdges({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    session: session as any,
+    labels: ["Person"],
+    props: { accountId: TEST_ACCOUNT_ID },
+    relationships,
+    createdBy: { agent: "maxy-admin", session: "sess-1", tool: "contact-create" },
+    expectedAccountId: TEST_ACCOUNT_ID,
+  });
+  assert.equal(res.edgesCreated, 1);
+});
+
+// Message subtypes (UserMessage, AssistantMessage, AdminMessage)
+// also qualify because the labels() array includes the parent :Message label.
+test("writeNodeWithEdges accepts :Person write with PRODUCED-from-Message edge", async () => {
+  const { session } = makeStubSession({
+    preCheckLabelsByTarget: new Map([
+      ["msg-id", ["Message", "UserMessage"]],
+    ]),
+  });
+  const relationships: GraphRelationship[] = [
+    { type: "PRODUCED", direction: "incoming", targetNodeId: "msg-id" },
+  ];
+  const res = await writeNodeWithEdges({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    session: session as any,
+    labels: ["Person"],
+    props: { accountId: TEST_ACCOUNT_ID },
+    relationships,
+    createdBy: { agent: "maxy-admin", session: "sess-1", tool: "contact-create" },
+    expectedAccountId: TEST_ACCOUNT_ID,
+  });
+  assert.equal(res.edgesCreated, 1);
+});
+
+// Defence-in-depth: a PRODUCED edge whose source is not in
+// {Task, Conversation, Message} does not satisfy the gate. Under the
+// Task 580 soft semantics the write still proceeds and the warn line fires —
+// the source-label allowlist now governs whether the write counts as
+// provenance-satisfied for the warn check, not whether it lands.
+test("writeNodeWithEdges accepts :Person write with PRODUCED edge from a non-provenance-source label and emits a warn line", async () => {
+  const { session } = makeStubSession({
+    preCheckLabelsByTarget: new Map([
+      ["business-id", ["LocalBusiness"]],
+    ]),
+  });
+  const relationships: GraphRelationship[] = [
+    { type: "PRODUCED", direction: "incoming", targetNodeId: "business-id" },
+  ];
+  const captured: string[] = [];
+  const originalWrite = process.stderr.write.bind(process.stderr);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  process.stderr.write = ((chunk: any) => {
+    captured.push(typeof chunk === "string" ? chunk : String(chunk));
+    return true;
+  }) as typeof process.stderr.write;
+  try {
+    const res = await writeNodeWithEdges({
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      session: session as any,
+      labels: ["Person"],
+      props: { accountId: TEST_ACCOUNT_ID },
+      relationships,
+      createdBy: { agent: "maxy-admin", session: "sess-1", tool: "memory-write" },
+      expectedAccountId: TEST_ACCOUNT_ID,
+    });
+    assert.equal(res.edgesCreated, 1);
+  } finally {
+    process.stderr.write = originalWrite;
+  }
+  const warnLine = captured.find((l) => l.includes("[graph-write] warn reason=missing-provenance"));
+  assert.ok(warnLine, `expected warn line; captured=${JSON.stringify(captured)}`);
+});
+
+test("writeNodeWithEdges accepts non-action-provenance label writes without Task edge", async () => {
+  const { session } = makeStubSession({
+    preCheckLabelsByTarget: new Map([["doc-id", ["KnowledgeDocument"]]]),
+  });
+  const relationships: GraphRelationship[] = [
+    { type: "ABOUT", direction: "outgoing", targetNodeId: "doc-id" },
+  ];
+  const res = await writeNodeWithEdges({
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    session: session as any,
+    labels: ["Question"], // not in ACTION_PROVENANCE_LABELS
+    props: { accountId: TEST_ACCOUNT_ID },
+    relationships,
+    createdBy: { agent: "maxy-admin", session: "sess-1", tool: "memory-write" },
+    expectedAccountId: TEST_ACCOUNT_ID,
+  });
+  assert.equal(res.edgesCreated, 1);
+});

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

@@ -0,0 +1,162 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  auditCypherWrite,
+  formatAuditLine,
+  type CypherWriteAuditInput,
+} from "../audit.js";
+
+const baseInput: Omit<CypherWriteAuditInput, "cypher"> = {
+  schema: {
+    labels: new Set(["Person", "Organization", "Task", "KnowledgeDocument"]),
+    relationshipTypes: new Set(["KNOWS", "PARTICIPANT", "REFERENCES", "MENTIONS", "PART_OF"]),
+  },
+  agentName: "database-operator",
+  sessionId: "session-abc",
+  nodesCreated: 0,
+  relsCreated: 0,
+  orphanIds: [],
+};
+
+test("audit: clean write with provenance + known types yields zero warnings", () => {
+  const cypher = `
+    MATCH (p:Person {name: $name}), (o:Organization {name: $org})
+    MERGE (p)-[r:KNOWS]->(o)
+    SET r.createdAt = datetime(),
+        r.createdByAgent = $agent,
+        r.createdByTool = 'graph-cypher-write',
+        r.createdBySession = $sessionId
+  `;
+  const warnings = auditCypherWrite({ ...baseInput, cypher, relsCreated: 1 });
+  assert.deepEqual(warnings, []);
+});
+
+test("audit: unknown edge type yields unknown-type-warning", () => {
+  const cypher = "MATCH (a:Person), (b:Person) CREATE (a)-[:HAS_KNOWN]->(b)";
+  const warnings = auditCypherWrite({ ...baseInput, cypher, relsCreated: 1 });
+  const w = warnings.find((x) => x.kind === "unknown-type-warning");
+  assert.ok(w, "expected unknown-type-warning");
+  assert.equal(w.kind, "unknown-type-warning");
+  if (w.kind === "unknown-type-warning") {
+    assert.equal(w.type, "HAS_KNOWN");
+  }
+});
+
+test("audit: known APOC edge in YIELD does not trip unknown-type", () => {
+  const cypher =
+    "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";
+  const warnings = auditCypherWrite({ ...baseInput, cypher });
+  const unknownTypeWarn = warnings.find((x) => x.kind === "unknown-type-warning");
+  assert.equal(unknownTypeWarn, undefined);
+});
+
+test("audit: CREATE with no provenance stamps yields missing-provenance-warning", () => {
+  const cypher = "CREATE (n:Person {name: 'Foo'})";
+  const warnings = auditCypherWrite({ ...baseInput, cypher, nodesCreated: 1 });
+  const w = warnings.find((x) => x.kind === "missing-provenance-warning");
+  assert.ok(w, "expected missing-provenance-warning");
+  if (w.kind === "missing-provenance-warning") {
+    assert.equal(w.created, 1);
+    assert.equal(w.stamped, 0);
+  }
+});
+
+test("audit: MERGE with createdBy* stamps does not trip missing-provenance", () => {
+  const cypher =
+    "MERGE (n:Person {email: $email}) ON CREATE SET n.createdByAgent = $agent, n.createdBySession = $sid";
+  const warnings = auditCypherWrite({ ...baseInput, cypher, nodesCreated: 1 });
+  const w = warnings.find((x) => x.kind === "missing-provenance-warning");
+  assert.equal(w, undefined);
+});
+
+test("audit: provenance check ignores stamps inside string literals", () => {
+  const cypher =
+    "CREATE (n:Person {bio: 'I have createdByAgent in my bio'})";
+  const warnings = auditCypherWrite({ ...baseInput, cypher, nodesCreated: 1 });
+  const w = warnings.find((x) => x.kind === "missing-provenance-warning");
+  assert.ok(w, "expected missing-provenance-warning despite stamp-like substring in literal");
+});
+
+test("audit: idempotent MERGE that matched existing node (nodesCreated=0) emits no missing-provenance-warning", () => {
+  // Reviewer-flagged false-positive case. MERGE (n:Person {email}) without
+  // ON CREATE SET stamps — static count = 1, stamps = 0. If the node
+  // already existed, upstream reports nodesCreated=0 and no provenance was
+  // needed; the audit must not warn.
+  const cypher = "MERGE (n:Person {email: $email})";
+  const warnings = auditCypherWrite({ ...baseInput, cypher, nodesCreated: 0 });
+  const w = warnings.find((x) => x.kind === "missing-provenance-warning");
+  assert.equal(w, undefined, "must not warn when nodesCreated=0");
+});
+
+test("audit: orphanIds populated yields orphan-warning", () => {
+  const warnings = auditCypherWrite({
+    ...baseInput,
+    cypher: "CREATE (n:Person)",
+    nodesCreated: 1,
+    orphanIds: ["4:abc:1", "4:abc:2"],
+  });
+  const w = warnings.find((x) => x.kind === "orphan-warning");
+  assert.ok(w, "expected orphan-warning");
+  if (w.kind === "orphan-warning") {
+    assert.deepEqual(w.orphanIds, ["4:abc:1", "4:abc:2"]);
+  }
+});
+
+test("audit: empty orphanIds emits no orphan-warning", () => {
+  const warnings = auditCypherWrite({
+    ...baseInput,
+    cypher: "MATCH (a:Person), (b:Person) CREATE (a)-[:KNOWS]->(b)",
+    relsCreated: 1,
+    orphanIds: [],
+  });
+  const w = warnings.find((x) => x.kind === "orphan-warning");
+  assert.equal(w, undefined);
+});
+
+test("formatAuditLine: accepted line includes counters + provenance", () => {
+  const line = formatAuditLine({
+    kind: "accepted",
+    cypherPrefix: "MATCH (a:Person) CREATE",
+    nodesCreated: 1,
+    relsCreated: 4,
+    agentName: "database-operator",
+    sessionId: "abc-123",
+  });
+  assert.match(line, /^\[graph-cypher-write\] accepted /);
+  assert.match(line, /nodesCreated=1/);
+  assert.match(line, /relsCreated=4/);
+  assert.match(line, /agentName=database-operator/);
+  assert.match(line, /sessionId=abc-123/);
+});
+
+test("formatAuditLine: orphan-warning line lists orphanIds", () => {
+  const line = formatAuditLine({
+    kind: "orphan-warning",
+    cypherPrefix: "CREATE (n:Person)",
+    orphanIds: ["4:abc:1", "4:abc:2"],
+  });
+  assert.match(line, /^\[graph-cypher-write\] orphan-warning /);
+  assert.match(line, /orphanIds=4:abc:1,4:abc:2/);
+});
+
+test("formatAuditLine: unknown-type-warning names the type", () => {
+  const line = formatAuditLine({
+    kind: "unknown-type-warning",
+    cypherPrefix: "CREATE (a)-[:HAS_KNOWN]->(b)",
+    type: "HAS_KNOWN",
+  });
+  assert.match(line, /^\[graph-cypher-write\] unknown-type-warning /);
+  assert.match(line, /type=HAS_KNOWN/);
+});
+
+test("formatAuditLine: missing-provenance-warning shows created vs stamped counts", () => {
+  const line = formatAuditLine({
+    kind: "missing-provenance-warning",
+    cypherPrefix: "CREATE (n:Person)",
+    created: 3,
+    stamped: 1,
+  });
+  assert.match(line, /^\[graph-cypher-write\] missing-provenance-warning /);
+  assert.match(line, /created=3/);
+  assert.match(line, /stamped=1/);
+});

package/payload/platform/lib/graph-write/src/audit.ts

@@ -0,0 +1,182 @@
+/**
+ * Post-write audit for the database-operator's raw `write_neo4j_cypher` tool
+ *. Sibling to `[graph-write] accepted` for the wrapped writers
+ * (`memory-write`, `contact-create`, etc.) — same module so the
+ * `[graph-*]` log family stays uniform across both write surfaces.
+ *
+ * Design posture:
+ *   - Static parse first. Pre-flight regex on the cypher text catches missing
+ *     provenance stamps and unknown edge types cheaply, no driver round-trip.
+ *   - Dynamic orphan detection is the caller's responsibility — the graph-mcp
+ *     shim runs the detection query against Neo4j after the upstream commits
+ *     and passes the resulting elementId list as `orphanIds`. Keeping the
+ *     module pure (no neo4j-driver import) makes it unit-testable without a
+ *     live database.
+ *   - Audit is observational. Warnings never block the write. The
+ *     prompt-level Graph Stewardship Doctrine in
+ *     [database-operator.md](../../../templates/specialists/agents/database-operator.md)
+ *     names the discipline; the audit is the verification stream.
+ *
+ * String literals are stripped before pattern checks so that property values
+ * containing words like `'createdByAgent in my bio'` cannot trip a false
+ * provenance count, and edge-like patterns inside quoted strings cannot
+ * trip a false unknown-type warning. The regex shape is duplicated from
+ * [cypher-validate.ts](../../graph-mcp/src/cypher-validate.ts) intentionally:
+ * graph-write does not depend on graph-mcp, and a one-line regex helper
+ * doesn't justify a third package. Drift in either copy is a regression
+ * surfaced by both the validator tests and the audit tests.
+ */
+
+export interface SchemaSnapshot {
+  readonly labels: ReadonlySet<string>;
+  readonly relationshipTypes: ReadonlySet<string>;
+}
+
+export interface CypherWriteAuditInput {
+  cypher: string;
+  schema: SchemaSnapshot;
+  agentName: string;
+  sessionId: string;
+  /** Counter from upstream response — drives missing-provenance arithmetic. */
+  nodesCreated: number;
+  /** Counter from upstream response — informational only. */
+  relsCreated: number;
+  /**
+   * elementIds of nodes the post-write orphan query identified. Caller scopes
+   * the query to (createdBySession, createdAt >= writeStartTimestamp) so this
+   * list cannot include nodes from prior writes in the same session. Empty
+   * array = no orphans (or no scope to check).
+   */
+  orphanIds: string[];
+}
+
+export type AuditWarning =
+  | { kind: "orphan-warning"; orphanIds: string[] }
+  | { kind: "unknown-type-warning"; type: string }
+  | { kind: "missing-provenance-warning"; created: number; stamped: number };
+
+export type AuditLine =
+  | {
+      kind: "accepted";
+      cypherPrefix: string;
+      nodesCreated: number;
+      relsCreated: number;
+      agentName: string;
+      sessionId: string;
+    }
+  | { kind: "orphan-warning"; cypherPrefix: string; orphanIds: string[] }
+  | { kind: "unknown-type-warning"; cypherPrefix: string; type: string }
+  | {
+      kind: "missing-provenance-warning";
+      cypherPrefix: string;
+      created: number;
+      stamped: number;
+    };
+
+// Mirrors cypher-validate's pattern. Captures TYPE(|TYPE)* alternation; the
+// audit splits on `|` to enumerate every referenced type.
+const EDGE_PATTERN = /\[[^\]]*?:([A-Z_][A-Za-z0-9_]*(?:\|[A-Z_][A-Za-z0-9_]*)*)[^\]]*?\]/g;
+
+// Counts CREATE (n:Label) and MERGE (n:Label) statements that introduce a
+// node. The trailing `[A-Z]` requires at least one label (so `CREATE INDEX`
+// and bare `CREATE (a)-[:R]->(b)` shapes don't trip this — bare patterns
+// reference a previously-MATCHed alias and don't introduce new nodes).
+const CREATE_OR_MERGE_NODE = /\b(?:CREATE|MERGE)\s*\(\s*[A-Za-z_][A-Za-z0-9_]*\s*:\s*[A-Z]/g;
+
+// Stamp tokens — at least one of these MUST appear per created node for the
+// write to satisfy provenance discipline. The audit counts occurrences;
+// stamp-count >= node-count is the pass criterion.
+const PROVENANCE_TOKEN = /\bcreatedBy(?:Agent|Tool|Session|Source)\b/g;
+
+function stripStringLiterals(cypher: string): string {
+  // Identical regex to cypher-validate.ts. Replaces single- and double-
+  // quoted literals with empty quotes so e.g. 'CREATE (n:Person)' inside a
+  // property value cannot inflate the create-count.
+  return cypher.replace(/'[^']*'|"[^"]*"/g, '""');
+}
+
+function extractEdgeTypes(cleaned: string): Set<string> {
+  const out = new Set<string>();
+  // Use String.matchAll for stateless iteration — no shared regex lastIndex.
+  for (const m of cleaned.matchAll(EDGE_PATTERN)) {
+    for (const t of m[1].split("|")) {
+      const clean = t.trim();
+      if (clean) out.add(clean);
+    }
+  }
+  return out;
+}
+
+function countCreateOrMergeNodes(cleaned: string): number {
+  const matches = cleaned.match(CREATE_OR_MERGE_NODE);
+  return matches ? matches.length : 0;
+}
+
+function countProvenanceStamps(cleaned: string): number {
+  const matches = cleaned.match(PROVENANCE_TOKEN);
+  return matches ? matches.length : 0;
+}
+
+export function auditCypherWrite(input: CypherWriteAuditInput): AuditWarning[] {
+  const warnings: AuditWarning[] = [];
+  const cleaned = stripStringLiterals(input.cypher);
+
+  // 1. Unknown edge type — cypher names a type not in the live ontology.
+  //    Enumerate every referenced type; emit one warning per unknown.
+  const referencedTypes = extractEdgeTypes(cleaned);
+  for (const t of referencedTypes) {
+    if (!input.schema.relationshipTypes.has(t)) {
+      warnings.push({ kind: "unknown-type-warning", type: t });
+    }
+  }
+
+  // 2. Missing provenance — count CREATE/MERGE-with-label statements vs
+  //    `createdBy*` token occurrences. Stamps may live in inline maps
+  //    (`{createdByAgent: $agent}`) or SET clauses; both shapes contribute
+  //    to the token count. The arithmetic is precision-imprecise — a
+  //    multi-stamp single CREATE inflates `stamped`, a multi-CREATE single
+  //    SET undercounts — but the directional signal (zero stamps for many
+  //    creates) catches the failure mode this audit exists to surface.
+  //
+  //    nodesCreated=0 short-circuits the check: the upstream counter is
+  //    ground truth for whether any node was actually persisted. An
+  //    idempotent MERGE that matched an existing node has a static
+  //    create-count of 1 but contributed no new node — no provenance was
+  //    needed, and warning here would be a false positive.
+  if (input.nodesCreated > 0) {
+    const createOrMergeNodes = countCreateOrMergeNodes(cleaned);
+    if (createOrMergeNodes > 0) {
+      const stamps = countProvenanceStamps(cleaned);
+      if (stamps < createOrMergeNodes) {
+        warnings.push({
+          kind: "missing-provenance-warning",
+          created: createOrMergeNodes,
+          stamped: stamps,
+        });
+      }
+    }
+  }
+
+  // 3. Orphans — caller-supplied. The dynamic detection happens at the
+  //    graph-mcp shim layer (which has the Neo4j driver); the audit module
+  //    only renders the warning shape.
+  if (input.orphanIds.length > 0) {
+    warnings.push({ kind: "orphan-warning", orphanIds: input.orphanIds });
+  }
+
+  return warnings;
+}
+
+export function formatAuditLine(line: AuditLine): string {
+  const prefixField = `query="${line.cypherPrefix.replace(/"/g, "'")}"`;
+  switch (line.kind) {
+    case "accepted":
+      return `[graph-cypher-write] accepted ${prefixField} nodesCreated=${line.nodesCreated} relsCreated=${line.relsCreated} agentName=${line.agentName} sessionId=${line.sessionId}`;
+    case "orphan-warning":
+      return `[graph-cypher-write] orphan-warning ${prefixField} orphanIds=${line.orphanIds.join(",")}`;
+    case "unknown-type-warning":
+      return `[graph-cypher-write] unknown-type-warning ${prefixField} type=${line.type}`;
+    case "missing-provenance-warning":
+      return `[graph-cypher-write] missing-provenance-warning ${prefixField} created=${line.created} stamped=${line.stamped}`;
+  }
+}