@lucern/contracts 1.0.3 → 1.0.4

package/dist/sdk-tools.contract.registry.js

@@ -1057,6 +1057,268 @@ var BATCH_CREATE_EDGES = {
   tier: "workhorse"
 };
 
+// src/tool-contracts.embeddings.ts
+var sharedEmbeddingParameters = {
+  topicId: {
+    type: "string",
+    description: "Topic whose epistemic node embedding index should be queried."
+  },
+  workspaceId: {
+    type: "string",
+    description: "Workspace scope for the embedding operation."
+  },
+  nodeType: {
+    type: "string",
+    description: "Optional epistemic node type filter."
+  },
+  embeddingModel: {
+    type: "string",
+    description: "Optional embedding model filter."
+  },
+  limit: {
+    type: "number",
+    description: "Maximum rows to return."
+  }
+};
+var LIST_MISSING_EMBEDDINGS = {
+  name: "list_missing_embeddings",
+  description: "List epistemic nodes missing fresh Convex embeddings. Like `git status` for the semantic index \u2014 shows which graph nodes still need indexing before retrieval can be trusted.",
+  parameters: sharedEmbeddingParameters,
+  required: ["topicId", "workspaceId"],
+  response: {
+    description: "Missing or stale embedding candidates",
+    fields: {
+      nodes: "array \u2014 node candidates missing fresh embeddings",
+      total: "number \u2014 candidate count",
+      nextCursor: "string | null"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var SEARCH_EMBEDDINGS = {
+  name: "search_embeddings",
+  description: "Search topic-scoped epistemic nodes through the Convex vector index. Like `git grep` with semantic distance \u2014 finds matching beliefs, questions, evidence, and other nodes even when wording differs.",
+  parameters: {
+    ...sharedEmbeddingParameters,
+    queryText: {
+      type: "string",
+      description: "Natural-language query to embed and search with."
+    },
+    queryVector: {
+      type: "array",
+      description: "Optional precomputed query vector."
+    },
+    minScore: {
+      type: "number",
+      description: "Optional minimum cosine-similarity score."
+    }
+  },
+  required: ["topicId", "workspaceId"],
+  response: {
+    description: "Vector search matches",
+    fields: {
+      results: "array \u2014 semantic matches with nodeId, nodeType, score, text, and provenance",
+      total: "number \u2014 match count",
+      nextCursor: "string | null"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var GET_EMBEDDINGS_BY_NODE_IDS = {
+  name: "get_embeddings_by_node_ids",
+  description: "Fetch embedding records for explicit epistemic node IDs. Like `git show` for semantic-index rows \u2014 inspects exactly which vectors exist for named graph nodes.",
+  parameters: {
+    ...sharedEmbeddingParameters,
+    nodeIds: {
+      type: "array",
+      description: "Epistemic node IDs to inspect."
+    }
+  },
+  required: ["topicId", "workspaceId", "nodeIds"],
+  response: {
+    description: "Embedding records for explicit node IDs",
+    fields: {
+      embeddings: "array \u2014 embedding metadata records",
+      total: "number \u2014 embedding count",
+      nextCursor: "string | null"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var QUEUE_EMBEDDING_BACKFILL = {
+  name: "queue_embedding_backfill",
+  description: "Queue background embedding generation for explicit epistemic nodes. Like `git add` for semantic-index work \u2014 stages graph nodes for the kernel backfill scheduler.",
+  parameters: {
+    ...sharedEmbeddingParameters,
+    nodeIds: {
+      type: "array",
+      description: "Epistemic node IDs to queue for embedding generation."
+    }
+  },
+  required: ["topicId", "workspaceId", "nodeIds"],
+  response: {
+    description: "Backfill queue receipt",
+    fields: {
+      queued: "number \u2014 queued node count",
+      nodeIds: "array \u2014 node IDs queued for embedding generation"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+
+// src/tool-contracts.hybrid-discovery.ts
+var hybridParameters = {
+  query: {
+    type: "string",
+    description: "Natural-language query text to resolve against the typed reasoning graph."
+  },
+  queryText: {
+    type: "string",
+    description: "Explicit query text alias for clients that separate command words from search text."
+  },
+  text: {
+    type: "string",
+    description: "Raw pasted text to use as a semantic retrieval seed."
+  },
+  topicId: {
+    type: "string",
+    description: "Optional topic scope. When omitted, semantic topic candidates are resolved first."
+  },
+  workspaceId: {
+    type: "string",
+    description: "Optional workspace scope used by semantic topic candidates and vector search."
+  },
+  nodeId: {
+    type: "string",
+    description: "Optional source node used for related-node or impact analysis."
+  },
+  include: {
+    type: "array",
+    description: "Result families to include, such as topics, nodes, worktrees, tasks, evidence, and edges."
+  },
+  via: {
+    type: "array",
+    description: "Retrieval methods to use: bm25, embeddings, edges, topic-tree, state, graph-algorithms."
+  },
+  depth: {
+    type: "number",
+    description: "Graph expansion depth. Defaults to 1 and is capped by the server."
+  },
+  limit: {
+    type: "number",
+    description: "Maximum rows per result family."
+  },
+  minScore: {
+    type: "number",
+    description: "Minimum semantic or fused score for candidate rows."
+  },
+  campaign: {
+    type: "number",
+    description: "Optional worktree campaign filter."
+  },
+  lane: {
+    type: "string",
+    description: "Optional worktree lane filter."
+  },
+  status: {
+    type: "string",
+    description: "Optional node, task, or worktree state/status filter."
+  },
+  nodeTypes: {
+    type: "array",
+    description: "Optional epistemic node types to include."
+  },
+  changedPaths: {
+    type: "array",
+    description: "Changed file paths used as impact-analysis query signals."
+  },
+  metadata: {
+    type: "object",
+    description: "Optional planner metadata for receipts and caller provenance."
+  }
+};
+var hybridResponse = {
+  description: "Hybrid semantic graph planner response with ranked result families and retrieval receipt.",
+  fields: {
+    results: "array \u2014 ranked mixed graph results with score, kind, source, and ranking signals",
+    topics: "array \u2014 candidate or traversed topics",
+    nodes: "array \u2014 matching epistemic nodes",
+    worktrees: "array \u2014 matching worktrees",
+    tasks: "array \u2014 matching tasks",
+    evidence: "array \u2014 matching evidence",
+    edges: "array \u2014 graph neighborhood edges",
+    receipt: "object \u2014 planner steps, candidate counts, ranking weights, source/cache posture"
+  }
+};
+var HYBRID_DISCOVER = {
+  name: "hybrid_discover",
+  description: "Discover typed reasoning graph context with BM25, embeddings, topic tree traversal, and graph neighborhoods. Like `git grep` plus `git log --graph` for Lucern's typed reasoning graph \u2014 finds the relevant branches of thought and explains why.",
+  parameters: hybridParameters,
+  required: [],
+  response: hybridResponse,
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var RESOLVE_TOPIC_SEMANTIC = {
+  name: "resolve_topic_semantic",
+  description: "Resolve an ambiguous topic using BM25, vector candidates, and topic-tree context. Like `git remote show` for a reasoning topic \u2014 finds the canonical branch and nearby branches before reading deeper.",
+  parameters: hybridParameters,
+  required: [],
+  response: hybridResponse,
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var EXPAND_GRAPH_NEIGHBORHOOD = {
+  name: "expand_graph_neighborhood",
+  description: "Expand a typed graph neighborhood around a query, topic, or node. Like `git log --graph --decorate` for reasoning state \u2014 follows typed edges and surfaces the surrounding context.",
+  parameters: hybridParameters,
+  required: [],
+  response: hybridResponse,
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var FIND_RELATED_NODES = {
+  name: "find_related_nodes",
+  description: "Find semantically and structurally related nodes across the reasoning graph. Like `git blame` across branches \u2014 starts from a node or text and finds nearby responsibility, evidence, and related claims.",
+  parameters: hybridParameters,
+  required: [],
+  response: hybridResponse,
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var ANALYZE_GRAPH_IMPACT = {
+  name: "analyze_graph_impact",
+  description: "Analyze which graph objects are affected by files, PR text, incidents, or campaign objectives. Like `git diff --name-only` plus semantic blame \u2014 maps a change signal onto topics, beliefs, tasks, and unresolved questions.",
+  parameters: hybridParameters,
+  required: [],
+  response: hybridResponse,
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var DETECT_GRAPH_DRIFT = {
+  name: "detect_graph_drift",
+  description: "Detect duplicate, stale, orphaned, or weakly linked reasoning graph surface. Like `git fsck` for the reasoning graph \u2014 finds semantic duplicates, stale docs/code references, and missing links.",
+  parameters: hybridParameters,
+  required: [],
+  response: hybridResponse,
+  ownerModule: "graph-intelligence",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+
 // src/lens-workflow.contract.ts
 var LENS_PERSPECTIVE_TYPES = [
   "investigation",
@@ -2418,6 +2680,26 @@ var COMPILE_CONTEXT = {
       type: "string",
       description: "Focus query used to resolve the topic and rank context items. Required when topicId is omitted."
     },
+    topicHint: {
+      type: "string",
+      description: "Optional natural-language topic hint used by the resolver when topicId is omitted or stale."
+    },
+    tags: {
+      type: "array",
+      description: "Optional resolver tags. Useful for narrowing topic inference without knowing the exact topic id."
+    },
+    touchedPaths: {
+      type: "array",
+      description: "Optional file or documentation paths used as resolver signals."
+    },
+    sourceRef: {
+      type: "string",
+      description: "Optional source reference used as a resolver signal, such as a worktree id, PR, or feature slug."
+    },
+    sourceKind: {
+      type: "string",
+      description: "Optional source kind used as a resolver signal, such as cli, worktree, commit, or docs."
+    },
     budget: {
       type: "number",
       description: "Token budget for prompt injection planning"
@@ -4267,6 +4549,16 @@ var MCP_TOOL_CONTRACTS = {
   search_beliefs: SEARCH_BELIEFS,
   find_contradictions: FIND_CONTRADICTIONS,
   bisect_confidence: BISECT_CONFIDENCE,
+  list_missing_embeddings: LIST_MISSING_EMBEDDINGS,
+  search_embeddings: SEARCH_EMBEDDINGS,
+  get_embeddings_by_node_ids: GET_EMBEDDINGS_BY_NODE_IDS,
+  queue_embedding_backfill: QUEUE_EMBEDDING_BACKFILL,
+  hybrid_discover: HYBRID_DISCOVER,
+  resolve_topic_semantic: RESOLVE_TOPIC_SEMANTIC,
+  expand_graph_neighborhood: EXPAND_GRAPH_NEIGHBORHOOD,
+  find_related_nodes: FIND_RELATED_NODES,
+  analyze_graph_impact: ANALYZE_GRAPH_IMPACT,
+  detect_graph_drift: DETECT_GRAPH_DRIFT,
   // Edges (commit)
   create_edge: CREATE_EDGE,
   update_edge: UPDATE_EDGE,