@lucern/contracts 1.0.2 → 1.0.4

package/dist/generated/schema-manifest.json

@@ -1834,6 +1834,14 @@
             "nodeId"
           ]
         },
+        {
+          "kind": "index",
+          "name": "by_topicId_nodeId",
+          "columns": [
+            "topicId",
+            "nodeId"
+          ]
+        },
         {
           "kind": "index",
           "name": "by_topicId_type",
@@ -1856,7 +1864,8 @@
           "dimensions": 1024,
           "filterFields": [
             "nodeType",
-            "createdBy"
+            "createdBy",
+            "topicId"
           ]
         }
       ],

package/dist/index.d.ts

@@ -14,7 +14,7 @@ export { CreateDomainEventInput, DOMAIN_EVENT_TYPES, DOMAIN_EVENT_VERSION, Domai
 export { DecodedPrefixedId, decodePrefixedId, encodePrefixedId, hasPrefixedIdPrefix } from './ids.contract.js';
 export { ComponentTableManifest, ComponentTableManifestSchema } from './schemas/component-table-manifest.js';
 export { SLOpinionInput, SLOpinionInputSchema } from './schemas/sl-opinion.js';
-export { E as EdgePolicyEntry, a as EdgePolicyEntrySchema, b as EdgePolicyManifest, c as EdgePolicyManifestSchema, d as EdgePolicyViolation, e as EpistemicNodeType, f as EpistemicNodeTypeSchema, G as GRAPH_REF_NODE_TYPES, g as GraphRef, h as GraphRefSchema, i as assertEdgePolicyAllowed, j as findEdgePolicy } from './edge-policy-manifest-4KOSP4nk.js';
+export { E as EdgePolicyEntry, a as EdgePolicyEntrySchema, b as EdgePolicyManifest, c as EdgePolicyManifestSchema, d as EdgePolicyViolation, e as EpistemicNodeType, f as EpistemicNodeTypeSchema, G as GRAPH_REF_NODE_TYPES, g as GraphRef, h as GraphRefSchema, i as assertEdgePolicyAllowed, j as findEdgePolicy } from './edge-policy-manifest-CT8Y4IeW.js';
 export { edgePolicyManifest } from './manifests/edge-policy-manifest.data.js';
 export { INFISICAL_RUNTIME_MANIFEST, InfisicalRuntimeManifest } from './manifests/infisical-runtime-manifest.js';
 export { CheckContext, CheckerKind, InvariantId, InvariantManifest, InvariantManifestSchema, InvariantResult, InvariantRule, InvariantSeverity } from './manifests/invariant-manifest.js';
@@ -58,6 +58,8 @@ import './tool-contracts.policy-observation-task-topic.js';
 import './tool-contracts.questions-listing.js';
 import './tool-contracts.js';
 import './tool-contracts.worktrees.js';
+import './tool-contracts.embeddings.js';
+import './tool-contracts.hybrid-discovery.js';
 import './schemas/enums.js';
 import './schemas/manifest.js';
 import './sdk-tools.contract.analytics.js';

package/dist/index.js

@@ -335,8 +335,14 @@ function convertSchemaInner(schema, state, path) {
   switch (schema._def.typeName) {
     case ZodFirstPartyTypeKind.ZodString:
       return { source: "v.string()", defaults: [] };
-    case ZodFirstPartyTypeKind.ZodNumber:
-      return { source: "v.number()", defaults: [] };
+    case ZodFirstPartyTypeKind.ZodNumber: {
+      const field = path.length >= 2 ? path[path.length - 2] : void 0;
+      const isArrayElement = path[path.length - 1] === "[]";
+      return {
+        source: isArrayElement && field && state.float64ArrayFields.has(field) ? "v.float64()" : "v.number()",
+        defaults: []
+      };
+    }
     case ZodFirstPartyTypeKind.ZodBigInt:
       return { source: "v.int64()", defaults: [] };
     case ZodFirstPartyTypeKind.ZodBoolean:
@@ -450,7 +456,8 @@ function zodToConvex(schema, options = {}) {
   const state = {
     location: options.location,
     purpose: options.purpose ?? "function_returns",
-    seenLazySchemas: /* @__PURE__ */ new WeakSet()
+    seenLazySchemas: /* @__PURE__ */ new WeakSet(),
+    float64ArrayFields: new Set(options.float64ArrayFields ?? [])
   };
   const converted = convertSchema(schema, state, []);
   return {
@@ -4892,6 +4899,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"
@@ -5218,6 +5245,268 @@ var OPEN_PULL_REQUEST = {
   tier: "showcase"
 };
 
+// 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/tool-contracts.ts
 var MCP_TOOL_CONTRACTS = {
   // Belief lifecycle (commit, amend, fork, archive)
@@ -5259,6 +5548,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,
@@ -7362,9 +7661,35 @@ var epistemicNodeEmbeddings = 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(),
@@ -7374,9 +7699,10 @@ var epistemicNodeEmbeddings = 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"] }
   ]
 });
 var groupMemberships = defineTable({
@@ -14775,7 +15101,7 @@ var PLATFORM_AI_SECRET_DEFINITIONS = [
     canonicalName: "OPENAI_API_KEY",
     owner: "lucern_platform",
     scope: "environment",
-    sourcePath: "/platform/ai",
+    sourcePath: "/tenants/lucern/shared/llm",
     environmentPolicy: "environment_specific",
     required: false,
     secret: true,
@@ -14800,7 +15126,7 @@ var PLATFORM_AI_SECRET_DEFINITIONS = [
     canonicalName: "ANTHROPIC_API_KEY",
     owner: "lucern_platform",
     scope: "environment",
-    sourcePath: "/platform/ai",
+    sourcePath: "/tenants/lucern/shared/llm",
     environmentPolicy: "environment_specific",
     required: false,
     secret: true,
@@ -14826,7 +15152,7 @@ var PLATFORM_AI_SECRET_DEFINITIONS = [
     aliases: ["GOOGLE_AI_API_KEY", "GOOGLE_GENERATIVE_AI_API_KEY"],
     owner: "lucern_platform",
     scope: "environment",
-    sourcePath: "/platform/ai",
+    sourcePath: "/tenants/lucern/shared/llm",
     environmentPolicy: "environment_specific",
     required: false,
     secret: true,
@@ -17874,7 +18200,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
       "required": false,
       "secret": true,
       "public": false,
-      "sourcePath": "/platform/ai",
+      "sourcePath": "/tenants/lucern/shared/llm",
       "environmentPolicy": "environment_specific",
       "consumers": [
         "lucern-ai-runtime",
@@ -19309,7 +19635,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
       "required": false,
       "secret": true,
       "public": false,
-      "sourcePath": "/platform/ai",
+      "sourcePath": "/tenants/lucern/shared/llm",
       "environmentPolicy": "environment_specific",
       "consumers": [
         "lucern-ai-runtime",
@@ -22614,7 +22940,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
       "required": false,
       "secret": true,
       "public": false,
-      "sourcePath": "/platform/ai",
+      "sourcePath": "/tenants/lucern/shared/llm",
       "environmentPolicy": "environment_specific",
       "consumers": [
         "lucern-ai-runtime",
@@ -32394,7 +32720,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
         "required": false,
         "secret": true,
         "public": false,
-        "sourcePath": "/platform/ai",
+        "sourcePath": "/tenants/lucern/shared/llm",
         "environmentPolicy": "environment_specific",
         "consumers": [
           "lucern-ai-runtime",
@@ -32714,7 +33040,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
         "required": false,
         "secret": true,
         "public": false,
-        "sourcePath": "/platform/ai",
+        "sourcePath": "/tenants/lucern/shared/llm",
         "environmentPolicy": "environment_specific",
         "consumers": [
           "lucern-ai-runtime",
@@ -33551,7 +33877,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
         "required": false,
         "secret": true,
         "public": false,
-        "sourcePath": "/platform/ai",
+        "sourcePath": "/tenants/lucern/shared/llm",
         "environmentPolicy": "environment_specific",
         "consumers": [
           "lucern-ai-runtime",
@@ -39147,7 +39473,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
         "required": false,
         "secret": true,
         "public": false,
-        "sourcePath": "/platform/ai",
+        "sourcePath": "/tenants/lucern/shared/llm",
         "environmentPolicy": "environment_specific",
         "consumers": [
           "lucern-ai-runtime",
@@ -39189,7 +39515,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
         "required": false,
         "secret": true,
         "public": false,
-        "sourcePath": "/platform/ai",
+        "sourcePath": "/tenants/lucern/shared/llm",
         "environmentPolicy": "environment_specific",
         "consumers": [
           "lucern-ai-runtime",
@@ -39345,7 +39671,7 @@ var GENERATED_INFISICAL_RUNTIME_ENV = {
         "required": false,
         "secret": true,
         "public": false,
-        "sourcePath": "/platform/ai",
+        "sourcePath": "/tenants/lucern/shared/llm",
         "environmentPolicy": "environment_specific",
         "consumers": [
           "lucern-ai-runtime",