@rubytech/create-maxy-code 0.1.132 → 0.1.138

package/payload/platform/lib/graph-search/src/query-expansion.ts

@@ -0,0 +1,129 @@
+/**
+ * Multi-query expansion via Haiku (Task 308).
+ *
+ * Generates 3-5 paraphrases of the user query so the hybrid pipeline runs
+ * each paraphrase against vector + BM25 in parallel and unions the
+ * candidate sets before fusion. Recovers recall on terse queries where the
+ * embedding's nearest-neighbour is unstable.
+ *
+ * The expansion runs through `@rubytech/oauth-llm` against Claude Haiku —
+ * the same OAuth-bearer path the admin classifiers use; no new SDK
+ * dependency and no Anthropic-API-key path. Cache is in-process, keyed by
+ * (accountId, normalisedQuery, retrievalClass), with a 1-hour TTL.
+ *
+ * Graceful degrade: if the LLM call fails, returns just the original
+ * query. The caller's hybrid pipeline still runs — just on one query
+ * instead of N — so missing paraphrases are a recall regression, not a
+ * fault.
+ */
+
+import { callOauthLlm } from "../../oauth-llm/dist/index.js";
+
+const CACHE_TTL_MS = 60 * 60 * 1000;
+const HAIKU_MODEL = "claude-haiku-4-5";
+const MAX_PARAPHRASES = 5;
+
+interface CacheEntry {
+  expansions: string[];
+  expiresAt: number;
+}
+
+const cache = new Map<string, CacheEntry>();
+
+export function clearExpansionCache(): void {
+  cache.clear();
+}
+
+export interface ExpandQueryParams {
+  query: string;
+  retrievalClass?: string;
+  accountId?: string;
+  /**
+   * Override the cache or skip it entirely (useful in tests). When
+   * `false`, the cache is read but never written; when `true` (default),
+   * both reads and writes are active.
+   */
+  useCache?: boolean;
+}
+
+/**
+ * Return `[query, ...paraphrases]` (original always first). On LLM
+ * failure returns `[query]` only and writes a single stderr line so the
+ * operator can see expansion is degrading without breaking search.
+ */
+export async function expandQuery(
+  params: ExpandQueryParams,
+): Promise<string[]> {
+  const { query, retrievalClass = "general", accountId = "", useCache = true } = params;
+  const normalised = query.trim().toLowerCase();
+  const cacheKey = `${accountId}::${retrievalClass}::${normalised}`;
+
+  if (useCache) {
+    const hit = cache.get(cacheKey);
+    if (hit && hit.expiresAt > Date.now()) {
+      return [query, ...hit.expansions];
+    }
+  }
+
+  const systemPrompt = [
+    "You generate paraphrases of a user query for hybrid graph search.",
+    "Return 3-5 alternative phrasings that preserve the user's intent but vary the surface form (synonyms, word order, entity-vs-attribute framing).",
+    "Do not change the entity names. Do not invent constraints the user did not state.",
+    "Output ONLY a JSON object via the provided tool; never free text.",
+  ].join("\n");
+
+  const classHint = retrievalClass === "general"
+    ? ""
+    : `The retrieval class is '${retrievalClass}' — tailor paraphrases accordingly.`;
+  const userMessage = [
+    `Original query: ${query}`,
+    classHint,
+  ].filter((s) => s.length > 0).join("\n");
+
+  const result = await callOauthLlm({
+    model: HAIKU_MODEL,
+    system: systemPrompt,
+    userMessage,
+    maxTokens: 512,
+    timeoutMs: 15_000,
+    tools: [
+      {
+        name: "emit_paraphrases",
+        description: "Emit 3-5 paraphrases of the user query.",
+        input_schema: {
+          type: "object",
+          properties: {
+            paraphrases: {
+              type: "array",
+              items: { type: "string" },
+              minItems: 3,
+              maxItems: MAX_PARAPHRASES,
+            },
+          },
+          required: ["paraphrases"],
+        },
+      },
+    ],
+    toolChoiceName: "emit_paraphrases",
+  });
+
+  if (result.kind !== "ok-tool") {
+    process.stderr.write(
+      `[graph-search:expansion-failed] cause=${result.kind === "fallback" ? result.cause : "unexpected"} query=${query.slice(0, 60).replace(/\s+/g, " ")}\n`,
+    );
+    return [query];
+  }
+
+  const raw = (result.input as { paraphrases?: unknown }).paraphrases;
+  if (!Array.isArray(raw)) return [query];
+  const expansions = raw
+    .filter((p): p is string => typeof p === "string" && p.trim().length > 0)
+    .map((p) => p.trim())
+    .slice(0, MAX_PARAPHRASES);
+
+  if (useCache) {
+    cache.set(cacheKey, { expansions, expiresAt: Date.now() + CACHE_TTL_MS });
+  }
+
+  return [query, ...expansions];
+}

package/payload/platform/lib/graph-search/src/route.ts

@@ -0,0 +1,70 @@
+/**
+ * Retrieval-class routing (Task 308).
+ *
+ * Consumes the `retrievalClass` field produced by Task 304's
+ * gateway-classifier (landed) and returns a per-class index plan: which
+ * labels to filter to, which fusion weights to favour, and whether to
+ * skip the lookup entirely.
+ *
+ * No new Haiku call here — this module is a pure deterministic mapping
+ * over the gateway's existing classification.
+ */
+
+export type RetrievalClass =
+  | "entity"
+  | "temporal"
+  | "event"
+  | "general"
+  | "none";
+
+export interface IndexPlan {
+  /** When true, the caller short-circuits and returns no results. */
+  skip: boolean;
+  /** Restrict vector + BM25 to these labels. Undefined means no filter. */
+  labelFilter?: string[];
+  /** Weight on the vector half of the (weighted-sum) fusion. */
+  vectorWeight: number;
+  /** Weight on the BM25 half of the (weighted-sum) fusion. */
+  bm25Weight: number;
+}
+
+/**
+ * Return the index plan for a retrieval class. Unknown values fall back
+ * to `general` rather than throwing — the routing is a soft hint and the
+ * caller's old behaviour is the safe default.
+ */
+export function pickIndexMix(retrievalClass: string | undefined): IndexPlan {
+  switch (retrievalClass) {
+    case "entity":
+      return {
+        skip: false,
+        labelFilter: ["Person", "Company", "Concept"],
+        vectorWeight: 0.85,
+        bm25Weight: 0.15,
+      };
+    case "temporal":
+      return {
+        skip: false,
+        labelFilter: ["Event"],
+        vectorWeight: 0.2,
+        bm25Weight: 0.8,
+      };
+    case "event":
+      return {
+        skip: false,
+        labelFilter: ["Event"],
+        vectorWeight: 0,
+        bm25Weight: 1,
+      };
+    case "none":
+      return { skip: true, vectorWeight: 0, bm25Weight: 0 };
+    case "general":
+    default:
+      if (retrievalClass && retrievalClass !== "general") {
+        process.stderr.write(
+          `[graph-search:unknown-class] rc=${retrievalClass} fallback=general\n`,
+        );
+      }
+      return { skip: false, vectorWeight: 0.7, bm25Weight: 0.3 };
+  }
+}

package/payload/platform/lib/graph-search/src/rrf-fusion.ts

@@ -0,0 +1,62 @@
+/**
+ * Reciprocal Rank Fusion (Task 308).
+ *
+ * Replaces the weighted-sum fusion (`0.7 * vector + 0.3 * bm25_norm`) when
+ * the `MAXY_GS_RRF` flag is on. RRF is robust to score-distribution drift
+ * between the vector and BM25 indexes — it sums `1 / (k + rank_i)` for each
+ * node across the ranked lists it appears in. Higher rank (lower index) →
+ * larger contribution; the constant `k` (default 60, per the gbrain
+ * default) smooths the long tail.
+ *
+ * The weighted-sum baseline stays as the fallback so flag flips are
+ * reversible without code edits.
+ */
+
+export interface FusionCandidate {
+  nodeId: string;
+}
+
+/**
+ * Fuse multiple ranked lists by Reciprocal Rank Fusion.
+ *
+ * Each input list is treated as already sorted (best first). For each
+ * candidate, score = sum over lists of `1 / (k + rank)`. Returns the union
+ * sorted by descending RRF score.
+ *
+ * Ties on RRF score are broken by the candidate's earliest appearance
+ * across the input lists (first-seen wins), which is deterministic given
+ * a deterministic input order.
+ */
+export function fuseRrf<T extends FusionCandidate>(
+  rankedLists: T[][],
+  k = 60,
+): Array<T & { rrfScore: number }> {
+  const scores = new Map<string, number>();
+  const representatives = new Map<string, T>();
+  const firstSeen = new Map<string, number>();
+  let order = 0;
+
+  for (const list of rankedLists) {
+    for (let rank = 0; rank < list.length; rank++) {
+      const candidate = list[rank];
+      const contribution = 1 / (k + rank);
+      const prior = scores.get(candidate.nodeId) ?? 0;
+      scores.set(candidate.nodeId, prior + contribution);
+      if (!representatives.has(candidate.nodeId)) {
+        representatives.set(candidate.nodeId, candidate);
+        firstSeen.set(candidate.nodeId, order++);
+      }
+    }
+  }
+
+  const out: Array<T & { rrfScore: number }> = [];
+  for (const [nodeId, rrfScore] of scores) {
+    const rep = representatives.get(nodeId)!;
+    out.push({ ...rep, rrfScore });
+  }
+  out.sort((a, b) => {
+    if (b.rrfScore !== a.rrfScore) return b.rrfScore - a.rrfScore;
+    return (firstSeen.get(a.nodeId)! - firstSeen.get(b.nodeId)!);
+  });
+  return out;
+}

package/payload/platform/neo4j/schema.cypher

@@ -2,6 +2,14 @@
 // Maxy Phase 0 — Neo4j Graph Schema
 // Schema.org compliant node types
 // ============================================================
+//
+// This file declares INDEXES and CONSTRAINTS only. The legal
+// (sourceLabel, EDGE_TYPE, targetLabel) triples for the typed-edge
+// auto-extraction pass (Task 305) live in
+// `platform/plugins/memory/mcp/src/lib/typed-edge-schema.ts`
+// as the TYPED_EDGE_ALLOWLIST constant. The Haiku prompt, the inline
+// validator, and the public docs are all generated from that one
+// constant; do not duplicate the enumeration here.
 
 // ----------------------------------------------------------
 // Constraints
@@ -361,7 +369,12 @@ ON EACH [n.name, n.firstName, n.lastName, n.givenName, n.familyName,
          n.email, n.note, n.label, n.value, n.message, n.preview, n.tagline,
          n.subject, n.bodyPreview, n.fromName, n.fromAddress, n.agentAddress, n.screeningReason,
          n.authority, n.contactValue, n.toolName,
-         n.displayName, n.slug, n.role];
+         n.displayName, n.slug, n.role,
+         n.compiledTruth];
+// `compiledTruth` (Task 306) is the authoritative-summary property the
+// compiled-truth + timeline knowledge model writes on Person/Company/Concept.
+// Indexed here so Task 308's compiledTruth boost path also benefits from BM25
+// hits against the summary text. No-op until 306 writes the property.
 
 // Project node — a standalone creative-output node distinct from
 // :Section. Anchored via (:UserProfile)-[:CREATED]->(:Project), with optional
@@ -1345,3 +1358,69 @@ OPTIONS {
     `vector.similarity_function`: 'cosine'
   }
 };
+
+// ----------------------------------------------------------
+// Compiled-truth + timeline knowledge model (Task 306) —
+// gbrain's "compiled truth above the rule, append-only timeline
+// below" pattern. Every :Person / :Organization / :Concept carries
+// an agent-rewritten summary (`compiledTruth`, ≤2000 chars) plus
+// a history of dated `:TimelineEvent` rows path-anchored via
+// `(entity)-[:HAS_TIMELINE_EVENT]->(:TimelineEvent)`. The
+// compiledTruth is what the agent reads when it needs a summary;
+// the timeline is what it cites and appends to.
+//
+// Naming:
+//   :TimelineEvent — distinct from :Event (scheduling plugin's
+//     schema:Event with eventId-unique). Collisions were the reason
+//     to fork; do not blend.
+//   :HAS_TIMELINE_EVENT — distinct from :HAS_EVENT (visitor analytics
+//     Session→PageView/Click/ScrollMilestone).
+//
+// MERGE doctrine: writers MUST path-anchor from the entity to defend
+// cross-account collisions, e.g.
+//   MATCH (e) WHERE elementId(e) = $entityId AND e.accountId = $accountId
+//   MERGE (e)-[:HAS_TIMELINE_EVENT]->(t:TimelineEvent {timelineEventId: $id})
+// Never label-only MERGE on :TimelineEvent.
+//
+// `kind` enum (5 values, no catch-all):
+//   mentioned | met | quoted | attended | transacted
+// Extractor refuses on ambiguity rather than collapsing to "other".
+//
+// `compiledTruth` source:
+//   compiledTruthSource = "rewriter" (default) — compiled-truth-rewriter
+//     library wrote it.
+//   compiledTruthSource = "operator" — operator overrode via the graph UI.
+//     Rewriter refuses to overwrite for 7 days unless forceRewrite=true.
+// ----------------------------------------------------------
+
+CREATE CONSTRAINT timeline_event_id_unique IF NOT EXISTS
+FOR (t:TimelineEvent) REQUIRE t.timelineEventId IS UNIQUE;
+
+CREATE INDEX timeline_event_account IF NOT EXISTS
+FOR (t:TimelineEvent) ON (t.accountId);
+
+CREATE INDEX timeline_event_occurred_at IF NOT EXISTS
+FOR (t:TimelineEvent) ON (t.occurredAt);
+
+CREATE INDEX timeline_event_kind IF NOT EXISTS
+FOR (t:TimelineEvent) ON (t.kind);
+
+CREATE VECTOR INDEX timeline_event_embedding IF NOT EXISTS
+FOR (t:TimelineEvent) ON (t.embedding)
+OPTIONS {
+  indexConfig: {
+    `vector.dimensions`: 768,
+    `vector.similarity_function`: 'cosine'
+  }
+};
+
+// `compiledTruthUpdatedAt` indices for stale-detection scans
+// (e.g. "find :Person with truth older than 7 days that has new events").
+CREATE INDEX person_compiled_truth_updated_at IF NOT EXISTS
+FOR (p:Person) ON (p.compiledTruthUpdatedAt);
+
+CREATE INDEX organization_compiled_truth_updated_at IF NOT EXISTS
+FOR (o:Organization) ON (o.compiledTruthUpdatedAt);
+
+CREATE INDEX concept_compiled_truth_updated_at IF NOT EXISTS
+FOR (c:Concept) ON (c.compiledTruthUpdatedAt);

package/payload/platform/plugins/admin/hooks/session-end-retrospective.sh

@@ -254,7 +254,7 @@ fi
 emit_log "gate-blocked sessionId=${SESSION_ID} reason=sentinel-absent"
 
 cat >&2 <<'INSTRUCTION'
-The operator signalled session end. Before this session can close, run the three-pass retrospective inside this same admin session — do not spawn a new session, do not background anything. Use the tools you already have.
+The operator signalled session end. Before this session can close, run the four-pass retrospective inside this same admin session — do not spawn a new session, do not background anything. Use the tools you already have.
 
 Pass 1 — Technical learnings. Walk this session for operator corrections and self-detected mistakes. For each one, delegate one graph write to `database-operator` via the Task tool, persisting a Learning or Correction node per the schema. Count what you write.
 
@@ -262,7 +262,9 @@ Pass 2 — Operator-relationship updates. Walk this session for tonal signals, r
 
 Pass 3 — Graph completeness sweep. Walk this session for any node, edge, or commitment that was discussed but not written to the graph in-flight. For each missing write, delegate to `database-operator` via the Task tool. Count what you write.
 
-Then call `session-retrospective-mark-complete` with the three counts and reply with one short paragraph in your house voice summarising what you wrote.
+Pass 4 — Typed-edge auto-extraction. Delegate to `database-operator` via the Task tool with a prompt naming the typed-edge pass and the session-start timestamp. The specialist calls `memory-typed-edge-pass` with that timestamp and returns the counters. Capture `nodesProcessed` and the accepted count from its reply.
+
+Then call `session-retrospective-mark-complete` with all five counts (learningsCount, preferencesCount, graphWriteCount, typedEdgesCount, nodesProcessed) and reply with one short paragraph in your house voice summarising what you wrote.
 INSTRUCTION
 
 exit 2

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -3094,13 +3094,15 @@ eagerTool(server, "action-edit", "Edit a pending action's input and then execute
 //   trigger → gate-blocked → complete → gate-released
 // against one operator sessionId. The release decision itself is the
 // JSONL grep — never the log line.
-server.tool("session-retrospective-mark-complete", "Marks the end-of-session retrospective complete. Call this AFTER walking the session for technical learnings, operator-relationship updates, and missing graph writes and persisting each one (Task-tool delegations to database-operator for graph writes, Write to SOUL.md for tonal updates). The counts you pass are the number of items you actually persisted in each pass. The session-end Stop hook gate releases on the presence of this tool_use in the transcript — calling it is the deterministic signal that the retrospective ran.", {
+server.tool("session-retrospective-mark-complete", "Marks the end-of-session retrospective complete. Call this AFTER walking the session for technical learnings, operator-relationship updates, missing graph writes, and the typed-edge auto-extraction pass — and persisting each one (Task-tool delegations to database-operator for graph writes and the typed-edge pass, Write to SOUL.md for tonal updates). The counts you pass are the number of items you actually persisted in each pass. The session-end Stop hook gate releases on the presence of this tool_use in the transcript — calling it is the deterministic signal that the retrospective ran.", {
     learningsCount: z.number().int().nonnegative().describe("Technical-learning / correction nodes you delegated to database-operator in this retrospective."),
     preferencesCount: z.number().int().nonnegative().describe("SOUL.md writes you made for tonal / working-style observations in this retrospective."),
     graphWriteCount: z.number().int().nonnegative().describe("Graph nodes/edges/commitments you delegated to database-operator for content that surfaced in the session but was not written in-flight."),
-}, async ({ learningsCount, preferencesCount, graphWriteCount }) => {
+    typedEdgesCount: z.number().int().nonnegative().describe("Typed edges accepted (MERGEd) by the typed-edge auto-extraction pass that database-operator ran in this retrospective. 0 is valid (no prose nodes touched or none yielded edges)."),
+    nodesProcessed: z.number().int().nonnegative().describe("Prose-bearing nodes the typed-edge pass enumerated and scanned in this retrospective. 0 is valid (no prose nodes since the session started)."),
+}, async ({ learningsCount, preferencesCount, graphWriteCount, typedEdgesCount, nodesProcessed }) => {
     const sessionId = process.env.SESSION_ID || "unknown";
-    const line = `complete sessionId=${sessionId} learningsCount=${learningsCount} preferencesCount=${preferencesCount} graphWriteCount=${graphWriteCount}`;
+    const line = `complete sessionId=${sessionId} learningsCount=${learningsCount} preferencesCount=${preferencesCount} graphWriteCount=${graphWriteCount} typedEdgesCount=${typedEdgesCount} nodesProcessed=${nodesProcessed}`;
     if (!PLATFORM_PORT) {
         // Module-init deliberately tolerates a missing PLATFORM_PORT
         // (lines ~62-71) so the MCP server does not loud-fail on plugin-
@@ -3131,7 +3133,7 @@ server.tool("session-retrospective-mark-complete", "Marks the end-of-session ret
     return {
         content: [{
                 type: "text",
-                text: `Retrospective marked complete (learnings=${learningsCount} preferences=${preferencesCount} graphWrites=${graphWriteCount}). Session is now free to end.`,
+                text: `Retrospective marked complete (learnings=${learningsCount} preferences=${preferencesCount} graphWrites=${graphWriteCount} typedEdges=${typedEdgesCount} nodesProcessed=${nodesProcessed}). Session is now free to end.`,
             }],
     };
 });