@lucern/events 1.0.3 → 1.0.5

package/dist/outbox.js

@@ -3919,6 +3919,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"
@@ -4245,6 +4265,268 @@ var OPEN_PULL_REQUEST = {
   tier: "showcase"
 };
 
+// ../contracts/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"
+};
+
+// ../contracts/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"
+};
+
 // ../contracts/src/tool-contracts.ts
 var MCP_TOOL_CONTRACTS = {
   // Belief lifecycle (commit, amend, fork, archive)
@@ -4286,6 +4568,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,
@@ -6356,9 +6648,35 @@ defineTable({
   category: "embedding",
   shape: z.object({
     "nodeId": idOf("epistemicNodes"),
+    "tenantId": z.string().optional(),
+    "workspaceId": z.string().optional(),
     "topicId": z.string().optional(),
-    "nodeType": z.enum(["belief", "question", "evidence", "answer", "synthesis", "theme", "source"]),
+    "nodeType": z.enum([
+      "decision",
+      "belief",
+      "question",
+      "theme",
+      "deal",
+      "topic",
+      "claim",
+      "evidence",
+      "synthesis",
+      "answer",
+      "atomic_fact",
+      "excerpt",
+      "source",
+      "company",
+      "person",
+      "investor",
+      "function",
+      "value_chain"
+    ]),
     "embedding": z.array(z.number()),
+    "embeddingModel": z.string().optional(),
+    "vectorDimensions": z.number().optional(),
+    "contentHash": z.string().optional(),
+    "textPreview": z.string().optional(),
+    "embeddedAt": z.number().optional(),
     "createdBy": z.string(),
     "hasAnswer": z.boolean().optional(),
     "confidence": z.number().optional(),
@@ -6368,9 +6686,10 @@ defineTable({
   }),
   indices: [
     { kind: "index", name: "by_nodeId", columns: ["nodeId"] },
+    { kind: "index", name: "by_topicId_nodeId", columns: ["topicId", "nodeId"] },
     { kind: "index", name: "by_topicId_type", columns: ["topicId", "nodeType"] },
     { kind: "index", name: "by_topicId", columns: ["topicId"] },
-    { kind: "vector", name: "by_embedding", vectorField: "embedding", dimensions: 1024, filterFields: ["nodeType", "createdBy"] }
+    { kind: "vector", name: "by_embedding", vectorField: "embedding", dimensions: 1024, filterFields: ["nodeType", "createdBy", "topicId"] }
   ]
 });
 defineTable({
@@ -11671,6 +11990,16 @@ var MCP_ANALYSIS_PLATFORM_OPERATION_NAMES = [
   "get_graph_structure_analysis",
   "list_graph_intelligence_queries",
   "run_graph_intelligence_query",
+  "list_missing_embeddings",
+  "search_embeddings",
+  "get_embeddings_by_node_ids",
+  "queue_embedding_backfill",
+  "hybrid_discover",
+  "resolve_topic_semantic",
+  "expand_graph_neighborhood",
+  "find_related_nodes",
+  "analyze_graph_impact",
+  "detect_graph_drift",
   "find_contradictions",
   "flag_contradiction",
   "detect_confirmation_bias",
@@ -13590,14 +13919,14 @@ function resolveCanonicalText(input) {
 }
 function createNodeInput(input, context) {
   const canonicalText = resolveCanonicalText(input);
-  const nodeType = String(input.nodeType);
+  const nodeType2 = String(input.nodeType);
   return withCreatedBy(
     compactRecord4({
-      globalId: typeof input.globalId === "string" && input.globalId.trim() ? input.globalId : generatedGlobalId(nodeType),
-      nodeType,
+      globalId: typeof input.globalId === "string" && input.globalId.trim() ? input.globalId : generatedGlobalId(nodeType2),
+      nodeType: nodeType2,
       subtype: input.subtype,
       canonicalText,
-      contentHash: typeof input.contentHash === "string" && input.contentHash.trim() ? input.contentHash : `${nodeType}:${canonicalText}`,
+      contentHash: typeof input.contentHash === "string" && input.contentHash.trim() ? input.contentHash : `${nodeType2}:${canonicalText}`,
       content: input.content,
       contentType: input.contentType,
       title: input.title,
@@ -15348,6 +15677,208 @@ var graphContracts = [
     args: lineageArgs
   })
 ];
+var nodeType = z.string().optional().describe("Optional epistemic node type filter.");
+var embeddingScopeArgs = z.object({
+  topicId: z.string().describe("Topic scope for the embedding operation."),
+  workspaceId: z.string().optional().describe("Workspace scope for the embedding operation."),
+  nodeType,
+  embeddingModel: z.string().optional().describe("Optional embedding model filter."),
+  limit: z.number().optional().describe("Maximum rows to return."),
+  cursor: z.string().optional().describe("Pagination cursor.")
+});
+var searchEmbeddingsArgs = embeddingScopeArgs.extend({
+  queryText: z.string().optional().describe("Natural-language query to embed and search with."),
+  queryVector: z.array(z.number()).optional().describe("Optional precomputed query vector."),
+  minScore: z.number().optional().describe("Minimum vector score.")
+});
+var getEmbeddingsArgs = embeddingScopeArgs.extend({
+  nodeIds: z.array(z.string()).describe("Epistemic node IDs to inspect.")
+});
+var queueEmbeddingBackfillArgs = getEmbeddingsArgs.extend({
+  metadata: z.record(z.unknown()).optional().describe("Backfill scheduling metadata.")
+});
+var passthroughInput = (input) => compactRecord4(input);
+var embeddingsContracts = [
+  surfaceContract({
+    name: "list_missing_embeddings",
+    kind: "query",
+    domain: "embeddings",
+    surfaceClass: "platform_public",
+    method: "GET",
+    path: "/embeddings/missing",
+    sdkNamespace: "embeddings",
+    sdkMethod: "listMissingForTopic",
+    summary: "List epistemic nodes missing fresh Convex embeddings.",
+    convex: {
+      module: "embeddings",
+      functionName: "listMissingForTopic",
+      kind: "query",
+      inputProjection: passthroughInput
+    },
+    args: embeddingScopeArgs
+  }),
+  surfaceContract({
+    name: "search_embeddings",
+    kind: "action",
+    domain: "embeddings",
+    surfaceClass: "platform_public",
+    path: "/embeddings/vector-search",
+    sdkNamespace: "embeddings",
+    sdkMethod: "vectorSearchByTopic",
+    summary: "Search topic-scoped epistemic nodes through the Convex vector index.",
+    idempotent: false,
+    effects: ["read"],
+    scopes: ["embeddings.read"],
+    convex: {
+      module: "embeddings",
+      functionName: "vectorSearchByTopic",
+      kind: "action",
+      inputProjection: passthroughInput
+    },
+    args: searchEmbeddingsArgs
+  }),
+  surfaceContract({
+    name: "get_embeddings_by_node_ids",
+    kind: "query",
+    domain: "embeddings",
+    surfaceClass: "platform_public",
+    path: "/embeddings/by-node-ids",
+    sdkNamespace: "embeddings",
+    sdkMethod: "getByNodeIds",
+    summary: "Fetch embedding records for explicit epistemic node IDs.",
+    convex: {
+      module: "embeddings",
+      functionName: "getByNodeIds",
+      kind: "query",
+      inputProjection: passthroughInput
+    },
+    args: getEmbeddingsArgs
+  }),
+  surfaceContract({
+    name: "queue_embedding_backfill",
+    kind: "mutation",
+    domain: "embeddings",
+    surfaceClass: "platform_public",
+    path: "/embeddings/backfill-queued",
+    sdkNamespace: "embeddings",
+    sdkMethod: "markEmbeddingBackfillQueued",
+    summary: "Queue background embedding generation for explicit epistemic nodes.",
+    convex: {
+      module: "embeddings",
+      functionName: "markEmbeddingBackfillQueued",
+      kind: "mutation",
+      inputProjection: passthroughInput
+    },
+    args: queueEmbeddingBackfillArgs
+  })
+];
+var includeKindSchema = z.enum([
+  "topics",
+  "nodes",
+  "worktrees",
+  "tasks",
+  "evidence",
+  "edges"
+]);
+var viaKindSchema = z.enum([
+  "bm25",
+  "embeddings",
+  "edges",
+  "topic-tree",
+  "state",
+  "graph-algorithms"
+]);
+var hybridPlannerArgs = z.object({
+  query: z.string().optional().describe("Natural-language query text."),
+  queryText: z.string().optional().describe("Explicit query text alias."),
+  text: z.string().optional().describe("Raw pasted text to use as query input."),
+  topicId: z.string().optional().describe("Optional topic scope."),
+  workspaceId: z.string().optional().describe("Optional workspace scope."),
+  nodeId: z.string().optional().describe("Optional source node."),
+  include: z.array(includeKindSchema).optional().describe("Result families to include."),
+  via: z.array(viaKindSchema).optional().describe("Retrieval methods to use."),
+  depth: z.number().optional().describe("Graph expansion depth."),
+  limit: z.number().optional().describe("Maximum rows per result family."),
+  minScore: z.number().optional().describe("Minimum fused score."),
+  campaign: z.number().optional().describe("Optional worktree campaign filter."),
+  lane: z.string().optional().describe("Optional worktree lane filter."),
+  status: z.string().optional().describe("Optional state/status filter."),
+  nodeType: z.string().optional().describe("Single node type filter."),
+  nodeTypes: z.array(z.string()).optional().describe("Node type filters."),
+  changedPaths: z.array(z.string()).optional().describe("Changed file path signals."),
+  metadata: z.record(z.unknown()).optional().describe("Planner metadata.")
+});
+var modeInput = (mode) => (input) => compactRecord4({
+  ...input,
+  mode,
+  queryText: input.queryText ?? input.query ?? input.text
+});
+function hybridContract(args) {
+  return surfaceContract({
+    name: args.name,
+    kind: "action",
+    domain: "hybrid",
+    surfaceClass: "platform_public",
+    path: args.path,
+    sdkNamespace: "hybrid",
+    sdkMethod: args.sdkMethod,
+    summary: args.summary,
+    idempotent: false,
+    effects: ["read"],
+    scopes: ["hybrid.read"],
+    convex: {
+      module: "hybridDiscovery",
+      functionName: args.sdkMethod,
+      kind: "action",
+      inputProjection: modeInput(args.mode)
+    },
+    args: hybridPlannerArgs
+  });
+}
+var hybridContracts = [
+  hybridContract({
+    name: "hybrid_discover",
+    path: "/hybrid/discover",
+    sdkMethod: "hybridDiscover",
+    summary: "Discover typed graph context with BM25, embeddings, topic tree traversal, and graph neighborhoods.",
+    mode: "discover"
+  }),
+  hybridContract({
+    name: "resolve_topic_semantic",
+    path: "/hybrid/topics/resolve",
+    sdkMethod: "resolveTopicSemantic",
+    summary: "Resolve an ambiguous topic using BM25, vector candidates, and topic-tree context.",
+    mode: "resolve_topic"
+  }),
+  hybridContract({
+    name: "expand_graph_neighborhood",
+    path: "/hybrid/neighborhood",
+    sdkMethod: "expandGraphNeighborhood",
+    summary: "Expand a typed graph neighborhood around a query, topic, or node.",
+    mode: "neighborhood"
+  }),
+  hybridContract({
+    name: "find_related_nodes",
+    path: "/hybrid/related-nodes",
+    sdkMethod: "findRelatedNodes",
+    summary: "Find semantically and structurally related nodes across the reasoning graph.",
+    mode: "related_nodes"
+  }),
+  hybridContract({
+    name: "analyze_graph_impact",
+    path: "/hybrid/impact",
+    sdkMethod: "analyzeGraphImpact",
+    summary: "Analyze which graph objects are affected by files, PR text, incidents, or campaign objectives.",
+    mode: "impact"
+  }),
+  hybridContract({
+    name: "detect_graph_drift",
+    path: "/hybrid/drift",
+    sdkMethod: "detectGraphDrift",
+    summary: "Detect duplicate, stale, orphaned, or weakly linked reasoning graph surface.",
+    mode: "drift"
+  })
+];
 
 // ../contracts/src/function-registry/contracts.ts
 var contractsContracts = [
@@ -16020,6 +16551,8 @@ var ALL_FUNCTION_CONTRACTS = [
   ...tasksContracts,
   ...edgesContracts,
   ...graphContracts,
+  ...embeddingsContracts,
+  ...hybridContracts,
   ...contractsContracts,
   ...judgmentsContracts,
   ...coordinationContracts,