@rubytech/create-maxy 1.0.704 → 1.0.706

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

@@ -0,0 +1,87 @@
+"use strict";
+/**
+ * Shared parser for `platform/neo4j/schema.cypher`.
+ *
+ * Two consumers today:
+ *   1. The admin SCHEMA prompt block (`platform/ui/app/lib/admin-schema-block.ts`,
+ *      Task 703) renders labels declared in schema.cypher into the agent's
+ *      system prompt.
+ *   2. The memory-plugin schema validator (Task 736) treats schema.cypher
+ *      declarations as the "promise" half of the recognised-label set —
+ *      labels that exist as constraints/indexes but may not yet have a node
+ *      in the graph (fresh-install bootstrap).
+ *
+ * The previous home was admin-schema-block.ts; that owner was wrong as
+ * soon as a second consumer arrived. Lifting here keeps a single source of
+ * truth and removes the cross-package shape coupling.
+ *
+ * Also exports a compact `levenshtein` for "did you mean?" suggestions on
+ * unknown labels — used by the memory-plugin validator. The graph-mcp
+ * cypher validator has its own copy in schema-cache.ts (private to the
+ * stale-miss heuristic); the duplication is intentional, since this
+ * exported one targets human-readable error UX, not refresh debouncing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseLabelsFromSchemaCypher = parseLabelsFromSchemaCypher;
+exports.levenshtein = levenshtein;
+exports.nearestLabel = nearestLabel;
+const LABEL_PATTERN = /FOR\s*\(\s*\w+\s*:\s*(\w+)\s*\)/g;
+/**
+ * Extract every Neo4j label declared in a `schema.cypher` file by scanning
+ * `FOR (alias:Label)` constraint and index forms. Returns a sorted, de-duped
+ * list. Pure function — no I/O.
+ */
+function parseLabelsFromSchemaCypher(schemaCypher) {
+    const found = new Set();
+    for (const match of schemaCypher.matchAll(LABEL_PATTERN)) {
+        found.add(match[1]);
+    }
+    return [...found].sort();
+}
+/**
+ * Standard iterative-DP Levenshtein. Used to suggest a near-match when an
+ * agent submits an unknown label — small alphabets, short strings, runs in
+ * microseconds. Identical algorithm to the private copy in schema-cache.ts;
+ * exported here so callers outside graph-mcp don't have to roll their own.
+ */
+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];
+}
+/**
+ * Find the closest label in `candidates` to `unknown` by edit distance.
+ * Returns null when the closest match is further than `maxDistance` (default
+ * 3) — beyond that a suggestion is more confusing than helpful.
+ */
+function nearestLabel(unknown, candidates, maxDistance = 3) {
+    let best = null;
+    let bestDist = Infinity;
+    for (const candidate of candidates) {
+        const d = levenshtein(unknown, candidate);
+        if (d < bestDist) {
+            bestDist = d;
+            best = candidate;
+        }
+    }
+    if (best === null || bestDist > maxDistance)
+        return null;
+    return best;
+}
+//# sourceMappingURL=schema-cypher-parser.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema-cypher-parser.js","sourceRoot":"","sources":["../src/schema-cypher-parser.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;AASH,kEAMC;AAQD,kCAgBC;AAOD,oCAgBC;AA5DD,MAAM,aAAa,GAAG,kCAAkC,CAAC;AAEzD;;;;GAIG;AACH,SAAgB,2BAA2B,CAAC,YAAoB;IAC9D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,KAAK,IAAI,YAAY,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;QACzD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACtB,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,CAAS,EAAE,CAAS;IAC9C,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtB,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,IAAI,GAAG,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,IAAI,IAAI,GAAG,IAAI,KAAK,CAAS,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAChD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACnC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3C,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;QACvE,CAAC;QACD,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAC1B,OAAe,EACf,UAA4B,EAC5B,WAAW,GAAG,CAAC;IAEf,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,QAAQ,GAAG,QAAQ,CAAC;IACxB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,CAAC,GAAG,WAAW,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC;YACjB,QAAQ,GAAG,CAAC,CAAC;YACb,IAAI,GAAG,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IACD,IAAI,IAAI,KAAK,IAAI,IAAI,QAAQ,GAAG,WAAW;QAAE,OAAO,IAAI,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/payload/platform/lib/graph-mcp/src/__tests__/schema-cypher-parser.test.ts

@@ -0,0 +1,99 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  parseLabelsFromSchemaCypher,
+  levenshtein,
+  nearestLabel,
+} from "../schema-cypher-parser.js";
+
+test("parseLabelsFromSchemaCypher: extracts labels from constraint and index forms", () => {
+  const text = `
+CREATE CONSTRAINT person_email IF NOT EXISTS
+FOR (p:Person) REQUIRE p.email IS UNIQUE;
+
+CREATE CONSTRAINT business_account IF NOT EXISTS
+FOR (b:LocalBusiness) REQUIRE b.accountId IS UNIQUE;
+
+CREATE INDEX admin_user_account IF NOT EXISTS
+FOR (au:AdminUser) ON (au.accountId);
+
+CREATE INDEX knowledge_doc IF NOT EXISTS
+FOR (k:KnowledgeDocument) ON (k.embedding) OPTIONS { ... };
+`;
+  const labels = parseLabelsFromSchemaCypher(text);
+  assert.deepEqual(labels, [
+    "AdminUser",
+    "KnowledgeDocument",
+    "LocalBusiness",
+    "Person",
+  ]);
+});
+
+test("parseLabelsFromSchemaCypher: deduplicates labels declared multiple times", () => {
+  const text = `
+FOR (p:Person) REQUIRE p.email IS UNIQUE;
+FOR (p:Person) REQUIRE p.telephone IS UNIQUE;
+FOR (p:Person) ON (p.status);
+`;
+  assert.deepEqual(parseLabelsFromSchemaCypher(text), ["Person"]);
+});
+
+test("parseLabelsFromSchemaCypher: returns sorted output", () => {
+  const text = `FOR (z:Zebra) ON (z.x); FOR (a:Aardvark) ON (a.x); FOR (m:Mongoose) ON (m.x);`;
+  assert.deepEqual(parseLabelsFromSchemaCypher(text), [
+    "Aardvark",
+    "Mongoose",
+    "Zebra",
+  ]);
+});
+
+test("parseLabelsFromSchemaCypher: ignores non-constraint cypher", () => {
+  const text = `
+MATCH (n:Person) RETURN n;
+CREATE (b:Business { name: 'X' });
+FOR (p:Person) REQUIRE p.email IS UNIQUE;
+`;
+  // MATCH/CREATE patterns don't include FOR, so they're ignored.
+  assert.deepEqual(parseLabelsFromSchemaCypher(text), ["Person"]);
+});
+
+test("parseLabelsFromSchemaCypher: empty input returns empty array", () => {
+  assert.deepEqual(parseLabelsFromSchemaCypher(""), []);
+});
+
+test("levenshtein: identical strings", () => {
+  assert.equal(levenshtein("Person", "Person"), 0);
+});
+
+test("levenshtein: substitution distance", () => {
+  // LocaIBusiness vs LocalBusiness — capital-I-as-l typo from the incident.
+  assert.equal(levenshtein("LocaIBusiness", "LocalBusiness"), 1);
+});
+
+test("levenshtein: insertion + deletion", () => {
+  assert.equal(levenshtein("Person", "Persons"), 1);
+  assert.equal(levenshtein("Persons", "Person"), 1);
+});
+
+test("levenshtein: handles empty strings", () => {
+  assert.equal(levenshtein("", "abc"), 3);
+  assert.equal(levenshtein("abc", ""), 3);
+  assert.equal(levenshtein("", ""), 0);
+});
+
+test("nearestLabel: finds the closest match", () => {
+  const candidates = ["Person", "LocalBusiness", "AdminUser"];
+  assert.equal(nearestLabel("LocaIBusiness", candidates), "LocalBusiness");
+  assert.equal(nearestLabel("AdminUsr", candidates), "AdminUser");
+});
+
+test("nearestLabel: returns null when no match within maxDistance", () => {
+  const candidates = ["Person", "LocalBusiness"];
+  assert.equal(nearestLabel("Quokka", candidates), null);
+  // Default maxDistance is 3; "abcde" is too far from any candidate.
+  assert.equal(nearestLabel("abcde", candidates, 1), null);
+});
+
+test("nearestLabel: empty candidates returns null", () => {
+  assert.equal(nearestLabel("Person", []), null);
+});

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

@@ -0,0 +1,84 @@
+/**
+ * Shared parser for `platform/neo4j/schema.cypher`.
+ *
+ * Two consumers today:
+ *   1. The admin SCHEMA prompt block (`platform/ui/app/lib/admin-schema-block.ts`,
+ *      Task 703) renders labels declared in schema.cypher into the agent's
+ *      system prompt.
+ *   2. The memory-plugin schema validator (Task 736) treats schema.cypher
+ *      declarations as the "promise" half of the recognised-label set —
+ *      labels that exist as constraints/indexes but may not yet have a node
+ *      in the graph (fresh-install bootstrap).
+ *
+ * The previous home was admin-schema-block.ts; that owner was wrong as
+ * soon as a second consumer arrived. Lifting here keeps a single source of
+ * truth and removes the cross-package shape coupling.
+ *
+ * Also exports a compact `levenshtein` for "did you mean?" suggestions on
+ * unknown labels — used by the memory-plugin validator. The graph-mcp
+ * cypher validator has its own copy in schema-cache.ts (private to the
+ * stale-miss heuristic); the duplication is intentional, since this
+ * exported one targets human-readable error UX, not refresh debouncing.
+ */
+
+const LABEL_PATTERN = /FOR\s*\(\s*\w+\s*:\s*(\w+)\s*\)/g;
+
+/**
+ * Extract every Neo4j label declared in a `schema.cypher` file by scanning
+ * `FOR (alias:Label)` constraint and index forms. Returns a sorted, de-duped
+ * list. Pure function — no I/O.
+ */
+export function parseLabelsFromSchemaCypher(schemaCypher: string): string[] {
+  const found = new Set<string>();
+  for (const match of schemaCypher.matchAll(LABEL_PATTERN)) {
+    found.add(match[1]);
+  }
+  return [...found].sort();
+}
+
+/**
+ * Standard iterative-DP Levenshtein. Used to suggest a near-match when an
+ * agent submits an unknown label — small alphabets, short strings, runs in
+ * microseconds. Identical algorithm to the private copy in schema-cache.ts;
+ * exported here so callers outside graph-mcp don't have to roll their own.
+ */
+export function levenshtein(a: string, b: string): number {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = new Array<number>(b.length + 1);
+  let curr = new Array<number>(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];
+}
+
+/**
+ * Find the closest label in `candidates` to `unknown` by edit distance.
+ * Returns null when the closest match is further than `maxDistance` (default
+ * 3) — beyond that a suggestion is more confusing than helpful.
+ */
+export function nearestLabel(
+  unknown: string,
+  candidates: Iterable<string>,
+  maxDistance = 3,
+): string | null {
+  let best: string | null = null;
+  let bestDist = Infinity;
+  for (const candidate of candidates) {
+    const d = levenshtein(unknown, candidate);
+    if (d < bestDist) {
+      bestDist = d;
+      best = candidate;
+    }
+  }
+  if (best === null || bestDist > maxDistance) return null;
+  return best;
+}

package/payload/platform/neo4j/edge-annotations.json

@@ -0,0 +1,134 @@
+{
+  "edges": {
+    "PART_OF": {
+      "direction": "(Message)-[:PART_OF]->(Conversation)",
+      "note": "Messages belong to exactly one Conversation. Do NOT use :HAS_MESSAGE — that edge does not exist."
+    },
+    "NEXT": {
+      "direction": "(Message)-[:NEXT]->(Message)",
+      "note": "Chain order within a Conversation. Each Message has at most one NEXT successor."
+    },
+    "ADMIN_OF": {
+      "direction": "(AdminUser)-[:ADMIN_OF]->(LocalBusiness)",
+      "note": "Device-level admin membership (see admin-add / admin-remove)."
+    },
+    "HAS_PROFILE": {
+      "direction": "(AdminUser)-[:HAS_PROFILE]->(UserProfile)",
+      "note": "Admin's profile node. Account scope lives on the `accountId` property of each node — do NOT add a redundant edge to LocalBusiness just to satisfy the write doctrine. Every MATCH filters by `{accountId: $accountId}`."
+    },
+    "AUTHORED_BY": {
+      "direction": "(Message)-[:AUTHORED_BY]->(Person)",
+      "note": "Message authorship (when the author is an identified Person)."
+    },
+    "HAS_TOOL_CALL": {
+      "direction": "(Message)-[:HAS_TOOL_CALL]->(ToolCall)",
+      "note": "Tool calls attached to an assistant message."
+    },
+    "HAS_RESULT": {
+      "direction": "(WorkflowStep|ToolCall)-[:HAS_RESULT]->(StepResult)",
+      "note": "Workflow step / tool-call outputs."
+    },
+    "HAS_STEP": {
+      "direction": "(Workflow)-[:HAS_STEP]->(WorkflowStep)",
+      "note": "Workflow composition."
+    },
+    "RUN_OF": {
+      "direction": "(WorkflowRun)-[:RUN_OF]->(Workflow)",
+      "note": "Workflow execution instance."
+    },
+    "HAS_SECTION": {
+      "direction": "(KnowledgeDocument)-[:HAS_SECTION]->(Section)",
+      "note": "Document hierarchy."
+    },
+    "HAS_CHUNK": {
+      "direction": "(Section)-[:HAS_CHUNK]->(Chunk)",
+      "note": "Section-to-embeddable-chunk."
+    },
+    "HAS_PREFERENCE": {
+      "direction": "(Person)-[:HAS_PREFERENCE]->(Preference)",
+      "note": "Person-scoped preferences (profile memory)."
+    },
+    "HAS_ACCESS": {
+      "direction": "(Person)-[:HAS_ACCESS]->(AccessGrant)",
+      "note": "Public agent access grants."
+    },
+    "HAS_TASK": {
+      "direction": "(Person|LocalBusiness)-[:HAS_TASK]->(Task)",
+      "note": "Task ownership / assignment."
+    },
+    "HAS_PRICING": {
+      "direction": "(Service)-[:HAS_PRICING]->(PriceSpecification)",
+      "note": "Service pricing."
+    },
+    "HAS_HOURS": {
+      "direction": "(LocalBusiness)-[:HAS_HOURS]->(OpeningHoursSpecification)",
+      "note": "Opening hours."
+    },
+    "HAS_FAQ": {
+      "direction": "(LocalBusiness)-[:HAS_FAQ]->(Question)",
+      "note": "FAQ attached to business."
+    },
+    "HAS_BRAND_ASSET": {
+      "direction": "(LocalBusiness)-[:HAS_BRAND_ASSET]->(DigitalDocument|ImageObject)",
+      "note": "Branding assets."
+    },
+    "OFFERS": {
+      "direction": "(LocalBusiness)-[:OFFERS]->(Service)",
+      "note": "Service catalogue."
+    },
+    "CONTAINS": {
+      "direction": "(KnowledgeDocument)-[:CONTAINS]->(Chunk)",
+      "note": "Flat document-to-chunk (alternative to HAS_SECTION then HAS_CHUNK)."
+    },
+    "REFERENCES": {
+      "direction": "(Message|KnowledgeDocument)-[:REFERENCES]->(*)",
+      "note": "Soft reference link."
+    },
+    "ABOUT": {
+      "direction": "(Review|Message)-[:ABOUT]->(*)",
+      "note": "Subject pointer."
+    },
+    "REPLY_TO": {
+      "direction": "(Email)-[:REPLY_TO]->(Email)",
+      "note": "Email threading."
+    },
+    "RECEIVED_BY": {
+      "direction": "(Email)-[:RECEIVED_BY]->(Person)",
+      "note": "Email recipient."
+    },
+    "RAISED_BY": {
+      "direction": "(ReviewAlert)-[:RAISED_BY]->(*)",
+      "note": "Alert provenance."
+    },
+    "AFFECTS": {
+      "direction": "(ReviewAlert)-[:AFFECTS]->(*)",
+      "note": "Alert impact surface."
+    },
+    "BLOCKS": {
+      "direction": "(Task)-[:BLOCKS]->(Task)",
+      "note": "Task dependency."
+    },
+    "OBSERVED_IN": {
+      "direction": "(*)-[:OBSERVED_IN]->(Conversation)",
+      "note": "Observation provenance."
+    }
+  },
+  "sublabels": {
+    "AdminConversation": {
+      "base": "Conversation",
+      "note": "Admin-only conversation (admin chat, not public)."
+    },
+    "PublicConversation": {
+      "base": "Conversation",
+      "note": "Public agent conversation (visitor-facing)."
+    },
+    "UserMessage": {
+      "base": "Message",
+      "note": "Message authored by the human user."
+    },
+    "AssistantMessage": {
+      "base": "Message",
+      "note": "Message authored by the assistant."
+    }
+  }
+}