@lucern/contracts 1.0.3 → 1.0.5

package/dist/tool-contracts.d.ts

@@ -3,6 +3,8 @@ export { McpParameterDef, McpResponseDef } from './tool-contracts.types.js';
 export { ADD_EVIDENCE, ARCHIVE_BELIEF, CREATE_BELIEF, CREATE_EPISTEMIC_CONTRACT, FLAG_CONTRADICTION, FORK_BELIEF, GET_BELIEF, MODULATE_CONFIDENCE, REFINE_BELIEF } from './tool-contracts.lifecycle.js';
 export { ADD_WORKTREE, MERGE, OPEN_PULL_REQUEST, PUSH } from './tool-contracts.worktrees.js';
 export { BATCH_CREATE_EDGES, BISECT_CONFIDENCE, CREATE_EDGE, FIND_CONTRADICTIONS, GET_AUDIT_TRAIL, GET_CONFIDENCE_HISTORY, GET_GRAPH_NEIGHBORHOOD, QUERY_LINEAGE, REMOVE_EDGE, REMOVE_EDGES_BETWEEN, SEARCH_BELIEFS, TRACE_ENTITY_IMPACT, TRAVERSE_GRAPH, UPDATE_EDGE } from './tool-contracts.graph.js';
+export { GET_EMBEDDINGS_BY_NODE_IDS, LIST_MISSING_EMBEDDINGS, QUEUE_EMBEDDING_BACKFILL, SEARCH_EMBEDDINGS } from './tool-contracts.embeddings.js';
+export { ANALYZE_GRAPH_IMPACT, DETECT_GRAPH_DRIFT, EXPAND_GRAPH_NEIGHBORHOOD, FIND_RELATED_NODES, HYBRID_DISCOVER, RESOLVE_TOPIC_SEMANTIC } from './tool-contracts.hybrid-discovery.js';
 export { APPLY_LENS_TO_TOPIC, ARCHIVE_EPISTEMIC_NODE, BATCH_CREATE_EPISTEMIC_NODES, CREATE_EPISTEMIC_NODE, CREATE_LENS, GET_EPISTEMIC_NODE, LIST_EPISTEMIC_NODES, LIST_LENSES, RECORD_JUDGMENT, REMOVE_LENS_FROM_TOPIC, SUPERSEDE_EPISTEMIC_NODE, UPDATE_EPISTEMIC_NODE, VERIFY_EPISTEMIC_NODE } from './tool-contracts.nodes-lenses.js';
 export { CREATE_EVIDENCE, DETECT_CONFIRMATION_BIAS, GET_EVIDENCE, GET_FALSIFICATION_QUESTIONS, GET_GRAPH_STRUCTURE_ANALYSIS, LINK_EVIDENCE, LINK_EVIDENCE_TO_BELIEF, LIST_EVIDENCE, LIST_GRAPH_INTELLIGENCE_QUERIES, RUN_GRAPH_INTELLIGENCE_QUERY, SEARCH_EVIDENCE } from './tool-contracts.intelligence-evidence.js';
 export { ACTIVATE_WORKTREE, ANSWER_QUESTION, ARCHIVE_QUESTION, COMPILE_CONTEXT, CREATE_ANSWER, CREATE_QUESTION, FIND_MISSING_QUESTIONS, GET_ANSWER, GET_HIGH_PRIORITY_QUESTIONS, GET_QUESTION, GET_WORKTREE, IDENTITY_WHOAMI, LINK_EVIDENCE_TO_QUESTION, LIST_ALL_WORKTREES, LIST_BELIEFS, LIST_CAMPAIGNS, LIST_QUESTIONS, LIST_WORKTREES, REFINE_QUESTION, RESOLVE_INTERACTIVE_PRINCIPAL, UPDATE_QUESTION_STATUS, UPDATE_WORKTREE_METADATA, UPDATE_WORKTREE_TARGETS } from './tool-contracts.questions-listing.js';

package/dist/tool-contracts.embeddings.d.ts

@@ -0,0 +1,8 @@
+import { McpToolContract } from './tool-contracts.types.js';
+
+declare const LIST_MISSING_EMBEDDINGS: McpToolContract;
+declare const SEARCH_EMBEDDINGS: McpToolContract;
+declare const GET_EMBEDDINGS_BY_NODE_IDS: McpToolContract;
+declare const QUEUE_EMBEDDING_BACKFILL: McpToolContract;
+
+export { GET_EMBEDDINGS_BY_NODE_IDS, LIST_MISSING_EMBEDDINGS, QUEUE_EMBEDDING_BACKFILL, SEARCH_EMBEDDINGS };

package/dist/tool-contracts.embeddings.js

@@ -0,0 +1,120 @@
+// 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"
+};
+
+export { GET_EMBEDDINGS_BY_NODE_IDS, LIST_MISSING_EMBEDDINGS, QUEUE_EMBEDDING_BACKFILL, SEARCH_EMBEDDINGS };
+//# sourceMappingURL=tool-contracts.embeddings.js.map
+//# sourceMappingURL=tool-contracts.embeddings.js.map

package/dist/tool-contracts.embeddings.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tool-contracts.embeddings.ts"],"names":[],"mappings":"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","file":"tool-contracts.embeddings.js","sourcesContent":["import type { McpToolContract } from \"./tool-contracts.types\";\n\nconst sharedEmbeddingParameters = {\n  topicId: {\n    type: \"string\",\n    description: \"Topic whose epistemic node embedding index should be queried.\",\n  },\n  workspaceId: {\n    type: \"string\",\n    description: \"Workspace scope for the embedding operation.\",\n  },\n  nodeType: {\n    type: \"string\",\n    description: \"Optional epistemic node type filter.\",\n  },\n  embeddingModel: {\n    type: \"string\",\n    description: \"Optional embedding model filter.\",\n  },\n  limit: {\n    type: \"number\",\n    description: \"Maximum rows to return.\",\n  },\n} satisfies McpToolContract[\"parameters\"];\n\nexport const LIST_MISSING_EMBEDDINGS: McpToolContract = {\n  name: \"list_missing_embeddings\",\n  description:\n    \"List epistemic nodes missing fresh Convex embeddings. \" +\n    \"Like `git status` for the semantic index — shows which graph nodes still need indexing before retrieval can be trusted.\",\n  parameters: sharedEmbeddingParameters,\n  required: [\"topicId\", \"workspaceId\"],\n  response: {\n    description: \"Missing or stale embedding candidates\",\n    fields: {\n      nodes: \"array — node candidates missing fresh embeddings\",\n      total: \"number — candidate count\",\n      nextCursor: \"string | null\",\n    },\n  },\n  ownerModule: \"reasoning-kernel\",\n  ontologyPrimitive: \"graph\",\n  tier: \"workhorse\",\n};\n\nexport const SEARCH_EMBEDDINGS: McpToolContract = {\n  name: \"search_embeddings\",\n  description:\n    \"Search topic-scoped epistemic nodes through the Convex vector index. \" +\n    \"Like `git grep` with semantic distance — finds matching beliefs, questions, evidence, and other nodes even when wording differs.\",\n  parameters: {\n    ...sharedEmbeddingParameters,\n    queryText: {\n      type: \"string\",\n      description: \"Natural-language query to embed and search with.\",\n    },\n    queryVector: {\n      type: \"array\",\n      description: \"Optional precomputed query vector.\",\n    },\n    minScore: {\n      type: \"number\",\n      description: \"Optional minimum cosine-similarity score.\",\n    },\n  },\n  required: [\"topicId\", \"workspaceId\"],\n  response: {\n    description: \"Vector search matches\",\n    fields: {\n      results: \"array — semantic matches with nodeId, nodeType, score, text, and provenance\",\n      total: \"number — match count\",\n      nextCursor: \"string | null\",\n    },\n  },\n  ownerModule: \"reasoning-kernel\",\n  ontologyPrimitive: \"graph\",\n  tier: \"showcase\",\n};\n\nexport const GET_EMBEDDINGS_BY_NODE_IDS: McpToolContract = {\n  name: \"get_embeddings_by_node_ids\",\n  description:\n    \"Fetch embedding records for explicit epistemic node IDs. \" +\n    \"Like `git show` for semantic-index rows — inspects exactly which vectors exist for named graph nodes.\",\n  parameters: {\n    ...sharedEmbeddingParameters,\n    nodeIds: {\n      type: \"array\",\n      description: \"Epistemic node IDs to inspect.\",\n    },\n  },\n  required: [\"topicId\", \"workspaceId\", \"nodeIds\"],\n  response: {\n    description: \"Embedding records for explicit node IDs\",\n    fields: {\n      embeddings: \"array — embedding metadata records\",\n      total: \"number — embedding count\",\n      nextCursor: \"string | null\",\n    },\n  },\n  ownerModule: \"reasoning-kernel\",\n  ontologyPrimitive: \"graph\",\n  tier: \"workhorse\",\n};\n\nexport const QUEUE_EMBEDDING_BACKFILL: McpToolContract = {\n  name: \"queue_embedding_backfill\",\n  description:\n    \"Queue background embedding generation for explicit epistemic nodes. \" +\n    \"Like `git add` for semantic-index work — stages graph nodes for the kernel backfill scheduler.\",\n  parameters: {\n    ...sharedEmbeddingParameters,\n    nodeIds: {\n      type: \"array\",\n      description: \"Epistemic node IDs to queue for embedding generation.\",\n    },\n  },\n  required: [\"topicId\", \"workspaceId\", \"nodeIds\"],\n  response: {\n    description: \"Backfill queue receipt\",\n    fields: {\n      queued: \"number — queued node count\",\n      nodeIds: \"array — node IDs queued for embedding generation\",\n    },\n  },\n  ownerModule: \"reasoning-kernel\",\n  ontologyPrimitive: \"graph\",\n  tier: \"workhorse\",\n};\n"]}

package/dist/tool-contracts.hybrid-discovery.d.ts

@@ -0,0 +1,10 @@
+import { McpToolContract } from './tool-contracts.types.js';
+
+declare const HYBRID_DISCOVER: McpToolContract;
+declare const RESOLVE_TOPIC_SEMANTIC: McpToolContract;
+declare const EXPAND_GRAPH_NEIGHBORHOOD: McpToolContract;
+declare const FIND_RELATED_NODES: McpToolContract;
+declare const ANALYZE_GRAPH_IMPACT: McpToolContract;
+declare const DETECT_GRAPH_DRIFT: McpToolContract;
+
+export { ANALYZE_GRAPH_IMPACT, DETECT_GRAPH_DRIFT, EXPAND_GRAPH_NEIGHBORHOOD, FIND_RELATED_NODES, HYBRID_DISCOVER, RESOLVE_TOPIC_SEMANTIC };

package/dist/tool-contracts.hybrid-discovery.js

@@ -0,0 +1,148 @@
+// 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"
+};
+
+export { ANALYZE_GRAPH_IMPACT, DETECT_GRAPH_DRIFT, EXPAND_GRAPH_NEIGHBORHOOD, FIND_RELATED_NODES, HYBRID_DISCOVER, RESOLVE_TOPIC_SEMANTIC };
+//# sourceMappingURL=tool-contracts.hybrid-discovery.js.map
+//# sourceMappingURL=tool-contracts.hybrid-discovery.js.map

package/dist/tool-contracts.hybrid-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tool-contracts.hybrid-discovery.ts"],"names":[],"mappings":"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","file":"tool-contracts.hybrid-discovery.js","sourcesContent":["import type { McpToolContract } from \"./tool-contracts.types\";\n\nconst hybridParameters = {\n  query: {\n    type: \"string\",\n    description: \"Natural-language query text to resolve against the typed reasoning graph.\",\n  },\n  queryText: {\n    type: \"string\",\n    description: \"Explicit query text alias for clients that separate command words from search text.\",\n  },\n  text: {\n    type: \"string\",\n    description: \"Raw pasted text to use as a semantic retrieval seed.\",\n  },\n  topicId: {\n    type: \"string\",\n    description: \"Optional topic scope. When omitted, semantic topic candidates are resolved first.\",\n  },\n  workspaceId: {\n    type: \"string\",\n    description: \"Optional workspace scope used by semantic topic candidates and vector search.\",\n  },\n  nodeId: {\n    type: \"string\",\n    description: \"Optional source node used for related-node or impact analysis.\",\n  },\n  include: {\n    type: \"array\",\n    description:\n      \"Result families to include, such as topics, nodes, worktrees, tasks, evidence, and edges.\",\n  },\n  via: {\n    type: \"array\",\n    description:\n      \"Retrieval methods to use: bm25, embeddings, edges, topic-tree, state, graph-algorithms.\",\n  },\n  depth: {\n    type: \"number\",\n    description: \"Graph expansion depth. Defaults to 1 and is capped by the server.\",\n  },\n  limit: {\n    type: \"number\",\n    description: \"Maximum rows per result family.\",\n  },\n  minScore: {\n    type: \"number\",\n    description: \"Minimum semantic or fused score for candidate rows.\",\n  },\n  campaign: {\n    type: \"number\",\n    description: \"Optional worktree campaign filter.\",\n  },\n  lane: {\n    type: \"string\",\n    description: \"Optional worktree lane filter.\",\n  },\n  status: {\n    type: \"string\",\n    description: \"Optional node, task, or worktree state/status filter.\",\n  },\n  nodeTypes: {\n    type: \"array\",\n    description: \"Optional epistemic node types to include.\",\n  },\n  changedPaths: {\n    type: \"array\",\n    description: \"Changed file paths used as impact-analysis query signals.\",\n  },\n  metadata: {\n    type: \"object\",\n    description: \"Optional planner metadata for receipts and caller provenance.\",\n  },\n} satisfies McpToolContract[\"parameters\"];\n\nconst hybridResponse = {\n  description: \"Hybrid semantic graph planner response with ranked result families and retrieval receipt.\",\n  fields: {\n    results: \"array — ranked mixed graph results with score, kind, source, and ranking signals\",\n    topics: \"array — candidate or traversed topics\",\n    nodes: \"array — matching epistemic nodes\",\n    worktrees: \"array — matching worktrees\",\n    tasks: \"array — matching tasks\",\n    evidence: \"array — matching evidence\",\n    edges: \"array — graph neighborhood edges\",\n    receipt: \"object — planner steps, candidate counts, ranking weights, source/cache posture\",\n  },\n} satisfies McpToolContract[\"response\"];\n\nexport const HYBRID_DISCOVER: McpToolContract = {\n  name: \"hybrid_discover\",\n  description:\n    \"Discover typed reasoning graph context with BM25, embeddings, topic tree traversal, and graph neighborhoods. \" +\n    \"Like `git grep` plus `git log --graph` for Lucern's typed reasoning graph — finds the relevant branches of thought and explains why.\",\n  parameters: hybridParameters,\n  required: [],\n  response: hybridResponse,\n  ownerModule: \"graph-intelligence\",\n  ontologyPrimitive: \"graph\",\n  tier: \"showcase\",\n};\n\nexport const RESOLVE_TOPIC_SEMANTIC: McpToolContract = {\n  name: \"resolve_topic_semantic\",\n  description:\n    \"Resolve an ambiguous topic using BM25, vector candidates, and topic-tree context. \" +\n    \"Like `git remote show` for a reasoning topic — finds the canonical branch and nearby branches before reading deeper.\",\n  parameters: hybridParameters,\n  required: [],\n  response: hybridResponse,\n  ownerModule: \"graph-intelligence\",\n  ontologyPrimitive: \"graph\",\n  tier: \"showcase\",\n};\n\nexport const EXPAND_GRAPH_NEIGHBORHOOD: McpToolContract = {\n  name: \"expand_graph_neighborhood\",\n  description:\n    \"Expand a typed graph neighborhood around a query, topic, or node. \" +\n    \"Like `git log --graph --decorate` for reasoning state — follows typed edges and surfaces the surrounding context.\",\n  parameters: hybridParameters,\n  required: [],\n  response: hybridResponse,\n  ownerModule: \"graph-intelligence\",\n  ontologyPrimitive: \"graph\",\n  tier: \"showcase\",\n};\n\nexport const FIND_RELATED_NODES: McpToolContract = {\n  name: \"find_related_nodes\",\n  description:\n    \"Find semantically and structurally related nodes across the reasoning graph. \" +\n    \"Like `git blame` across branches — starts from a node or text and finds nearby responsibility, evidence, and related claims.\",\n  parameters: hybridParameters,\n  required: [],\n  response: hybridResponse,\n  ownerModule: \"graph-intelligence\",\n  ontologyPrimitive: \"graph\",\n  tier: \"showcase\",\n};\n\nexport const ANALYZE_GRAPH_IMPACT: McpToolContract = {\n  name: \"analyze_graph_impact\",\n  description:\n    \"Analyze which graph objects are affected by files, PR text, incidents, or campaign objectives. \" +\n    \"Like `git diff --name-only` plus semantic blame — maps a change signal onto topics, beliefs, tasks, and unresolved questions.\",\n  parameters: hybridParameters,\n  required: [],\n  response: hybridResponse,\n  ownerModule: \"graph-intelligence\",\n  ontologyPrimitive: \"graph\",\n  tier: \"showcase\",\n};\n\nexport const DETECT_GRAPH_DRIFT: McpToolContract = {\n  name: \"detect_graph_drift\",\n  description:\n    \"Detect duplicate, stale, orphaned, or weakly linked reasoning graph surface. \" +\n    \"Like `git fsck` for the reasoning graph — finds semantic duplicates, stale docs/code references, and missing links.\",\n  parameters: hybridParameters,\n  required: [],\n  response: hybridResponse,\n  ownerModule: \"graph-intelligence\",\n  ontologyPrimitive: \"graph\",\n  tier: \"showcase\",\n};\n"]}

package/dist/tool-contracts.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,
@@ -4393,6 +4685,6 @@ function validateGitSemantics(tool) {
   return { valid: true };
 }
 
-export { ACTIVATE_WORKTREE, ADD_EVIDENCE, ADD_WORKTREE, ANALYZE_TOPIC_DENSITY, ANSWER_QUESTION, APPLY_AUTO_BRANCHING, APPLY_LENS_TO_TOPIC, APPLY_ONTOLOGY, ARCHIVE_BELIEF, ARCHIVE_EPISTEMIC_NODE, ARCHIVE_ONTOLOGY, ARCHIVE_QUESTION, BATCH_CREATE_EDGES, BATCH_CREATE_EPISTEMIC_NODES, BEGIN_BUILD_SESSION, BISECT_CONFIDENCE, BROADCAST_MESSAGE, CHECK_PERMISSION, CLAIM_FILES, COMPILE_CONTEXT, COMPLETE_TASK, CREATE_ANSWER, CREATE_BELIEF, CREATE_EDGE, CREATE_EPISTEMIC_CONTRACT, CREATE_EPISTEMIC_NODE, CREATE_EVIDENCE, CREATE_LENS, CREATE_ONTOLOGY, CREATE_ONTOLOGY_VERSION, CREATE_QUESTION, CREATE_TASK, CREATE_TOPIC, DEPRECATE_ONTOLOGY_VERSION, DETECT_CONFIRMATION_BIAS, DISCOVER, DISCOVER_ENTITY_CONNECTIONS, END_SESSION, EVALUATE_CONTRACT, FILTER_BY_PERMISSION, FIND_CONTRADICTIONS, FIND_MISSING_QUESTIONS, FLAG_CONTRADICTION, FORK_BELIEF, GENERATE_SESSION_HANDOFF, GET_AGENT_INBOX, GET_ANSWER, GET_AUDIT_TRAIL, GET_BELIEF, GET_CHANGE_HISTORY, GET_CODE_CONTEXT, GET_CONFIDENCE_HISTORY, GET_CONTRACT_STATUS, GET_EPISTEMIC_NODE, GET_EVIDENCE, GET_FAILURE_LOG, GET_FALSIFICATION_QUESTIONS, GET_GRAPH_GAPS, GET_GRAPH_NEIGHBORHOOD, GET_GRAPH_STRUCTURE_ANALYSIS, GET_HIGH_PRIORITY_QUESTIONS, GET_LATTICE_COVERAGE, GET_OBSERVATION_CONTEXT, GET_ONTOLOGY, GET_QUESTION, GET_TOPIC, GET_TOPIC_COVERAGE, GET_TOPIC_GRAPH_SPINE, GET_TOPIC_TREE, GET_WORKTREE, GIT_SEMANTIC_REQUIRED_TOOLS, HEARTBEAT_SESSION, IDENTITY_WHOAMI, INGEST_OBSERVATION, LINK_EVIDENCE, LINK_EVIDENCE_TO_BELIEF, LINK_EVIDENCE_TO_QUESTION, LIST_ACTIVE_SESSIONS, LIST_ALL_WORKTREES, LIST_BELIEFS, LIST_CAMPAIGNS, LIST_EPISTEMIC_NODES, LIST_EVIDENCE, LIST_GRAPH_INTELLIGENCE_QUERIES, LIST_LENSES, LIST_ONTOLOGIES, LIST_QUESTIONS, LIST_TASKS, LIST_TOPICS, LIST_WORKTREES, MANAGE_WRITE_POLICY, MATCH_ENTITY_TYPE, MATERIALIZE_TOPIC_GRAPH, MCP_TOOL_CONTRACTS, MERGE, MODULATE_CONFIDENCE, OPEN_PULL_REQUEST, PIPELINE_SNAPSHOT, PUBLISH_ONTOLOGY_VERSION, PUSH, QUERY_LINEAGE, RECORD_ATTEMPT, RECORD_JUDGMENT, RECORD_SCOPE_LEARNING, REFINE_BELIEF, REFINE_QUESTION, REGISTER_SESSION, REMOVE_EDGE, REMOVE_EDGES_BETWEEN, REMOVE_LENS_FROM_TOPIC, RESOLVE_EFFECTIVE_ONTOLOGY, RESOLVE_INTERACTIVE_PRINCIPAL, RUN_GRAPH_INTELLIGENCE_QUERY, SEARCH_BELIEFS, SEARCH_EVIDENCE, SEED_BELIEF_LATTICE, SEND_AGENT_MESSAGE, SUPERSEDE_EPISTEMIC_NODE, TRACE_ENTITY_IMPACT, TRAVERSE_GRAPH, TRIGGER_BELIEF_REVIEW, UPDATE_EDGE, UPDATE_EPISTEMIC_NODE, UPDATE_ONTOLOGY, UPDATE_QUESTION_STATUS, UPDATE_TASK, UPDATE_TOPIC, UPDATE_WORKTREE_METADATA, UPDATE_WORKTREE_TARGETS, VERIFY_EPISTEMIC_NODE, validateGitSemantics };
+export { ACTIVATE_WORKTREE, ADD_EVIDENCE, ADD_WORKTREE, ANALYZE_GRAPH_IMPACT, ANALYZE_TOPIC_DENSITY, ANSWER_QUESTION, APPLY_AUTO_BRANCHING, APPLY_LENS_TO_TOPIC, APPLY_ONTOLOGY, ARCHIVE_BELIEF, ARCHIVE_EPISTEMIC_NODE, ARCHIVE_ONTOLOGY, ARCHIVE_QUESTION, BATCH_CREATE_EDGES, BATCH_CREATE_EPISTEMIC_NODES, BEGIN_BUILD_SESSION, BISECT_CONFIDENCE, BROADCAST_MESSAGE, CHECK_PERMISSION, CLAIM_FILES, COMPILE_CONTEXT, COMPLETE_TASK, CREATE_ANSWER, CREATE_BELIEF, CREATE_EDGE, CREATE_EPISTEMIC_CONTRACT, CREATE_EPISTEMIC_NODE, CREATE_EVIDENCE, CREATE_LENS, CREATE_ONTOLOGY, CREATE_ONTOLOGY_VERSION, CREATE_QUESTION, CREATE_TASK, CREATE_TOPIC, DEPRECATE_ONTOLOGY_VERSION, DETECT_CONFIRMATION_BIAS, DETECT_GRAPH_DRIFT, DISCOVER, DISCOVER_ENTITY_CONNECTIONS, END_SESSION, EVALUATE_CONTRACT, EXPAND_GRAPH_NEIGHBORHOOD, FILTER_BY_PERMISSION, FIND_CONTRADICTIONS, FIND_MISSING_QUESTIONS, FIND_RELATED_NODES, FLAG_CONTRADICTION, FORK_BELIEF, GENERATE_SESSION_HANDOFF, GET_AGENT_INBOX, GET_ANSWER, GET_AUDIT_TRAIL, GET_BELIEF, GET_CHANGE_HISTORY, GET_CODE_CONTEXT, GET_CONFIDENCE_HISTORY, GET_CONTRACT_STATUS, GET_EMBEDDINGS_BY_NODE_IDS, GET_EPISTEMIC_NODE, GET_EVIDENCE, GET_FAILURE_LOG, GET_FALSIFICATION_QUESTIONS, GET_GRAPH_GAPS, GET_GRAPH_NEIGHBORHOOD, GET_GRAPH_STRUCTURE_ANALYSIS, GET_HIGH_PRIORITY_QUESTIONS, GET_LATTICE_COVERAGE, GET_OBSERVATION_CONTEXT, GET_ONTOLOGY, GET_QUESTION, GET_TOPIC, GET_TOPIC_COVERAGE, GET_TOPIC_GRAPH_SPINE, GET_TOPIC_TREE, GET_WORKTREE, GIT_SEMANTIC_REQUIRED_TOOLS, HEARTBEAT_SESSION, HYBRID_DISCOVER, IDENTITY_WHOAMI, INGEST_OBSERVATION, LINK_EVIDENCE, LINK_EVIDENCE_TO_BELIEF, LINK_EVIDENCE_TO_QUESTION, LIST_ACTIVE_SESSIONS, LIST_ALL_WORKTREES, LIST_BELIEFS, LIST_CAMPAIGNS, LIST_EPISTEMIC_NODES, LIST_EVIDENCE, LIST_GRAPH_INTELLIGENCE_QUERIES, LIST_LENSES, LIST_MISSING_EMBEDDINGS, LIST_ONTOLOGIES, LIST_QUESTIONS, LIST_TASKS, LIST_TOPICS, LIST_WORKTREES, MANAGE_WRITE_POLICY, MATCH_ENTITY_TYPE, MATERIALIZE_TOPIC_GRAPH, MCP_TOOL_CONTRACTS, MERGE, MODULATE_CONFIDENCE, OPEN_PULL_REQUEST, PIPELINE_SNAPSHOT, PUBLISH_ONTOLOGY_VERSION, PUSH, QUERY_LINEAGE, QUEUE_EMBEDDING_BACKFILL, RECORD_ATTEMPT, RECORD_JUDGMENT, RECORD_SCOPE_LEARNING, REFINE_BELIEF, REFINE_QUESTION, REGISTER_SESSION, REMOVE_EDGE, REMOVE_EDGES_BETWEEN, REMOVE_LENS_FROM_TOPIC, RESOLVE_EFFECTIVE_ONTOLOGY, RESOLVE_INTERACTIVE_PRINCIPAL, RESOLVE_TOPIC_SEMANTIC, RUN_GRAPH_INTELLIGENCE_QUERY, SEARCH_BELIEFS, SEARCH_EMBEDDINGS, SEARCH_EVIDENCE, SEED_BELIEF_LATTICE, SEND_AGENT_MESSAGE, SUPERSEDE_EPISTEMIC_NODE, TRACE_ENTITY_IMPACT, TRAVERSE_GRAPH, TRIGGER_BELIEF_REVIEW, UPDATE_EDGE, UPDATE_EPISTEMIC_NODE, UPDATE_ONTOLOGY, UPDATE_QUESTION_STATUS, UPDATE_TASK, UPDATE_TOPIC, UPDATE_WORKTREE_METADATA, UPDATE_WORKTREE_TARGETS, VERIFY_EPISTEMIC_NODE, validateGitSemantics };
 //# sourceMappingURL=tool-contracts.js.map
 //# sourceMappingURL=tool-contracts.js.map