@lucern/mcp 0.3.0-alpha.6 → 0.3.0-alpha.8

package/dist/runtime.js

@@ -6,6 +6,50 @@ import { v } from 'convex/values';
 import 'crypto';
 import * as os from 'os';
 
+// ../../apps/mcp-server/src/logging.ts
+function isMcpDebugEnabled() {
+  const debug = process.env.LUCERN_MCP_DEBUG?.trim().toLowerCase();
+  return debug === "1" || debug === "true" || debug === "yes";
+}
+function formatUnknownError(error) {
+  if (error instanceof Error) {
+    const cause = error.cause;
+    const message = `${error.name}: ${error.message}`;
+    if (cause === void 0) {
+      return message;
+    }
+    return `${message}; cause=${formatUnknownError(cause)}`;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return Object.prototype.toString.call(error);
+  }
+}
+function stringifyForDebug(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return Object.prototype.toString.call(value);
+  }
+}
+function debugMcp(message, context) {
+  if (!isMcpDebugEnabled()) {
+    return;
+  }
+  const suffix = context ? ` ${stringifyForDebug(context)}` : "";
+  console.error(`[lucern-debug] ${message}${suffix}`);
+}
+function debugMcpError(message, error) {
+  debugMcp(message, { error: formatUnknownError(error) });
+}
+
 // ../../apps/mcp-server/src/handlers/sdk.ts
 var handlerSdkClientCache = /* @__PURE__ */ new WeakMap();
 async function resolveOntologyFromLookup(baseClient, input) {
@@ -129,7 +173,11 @@ function readStringArray(value) {
         if (Array.isArray(parsed)) {
           return readStringArray(parsed);
         }
-      } catch {
+      } catch (error) {
+        debugMcpError("Failed to parse string array payload", {
+          value: normalized,
+          error
+        });
       }
     }
   }
@@ -5025,6 +5073,11 @@ var TENANT_CLIENT_INSTALLABLE_PACKAGES = [
     role: "sdk_dependency",
     directTenantImport: false
   },
+  {
+    packageName: "@lucern/graph-sync",
+    role: "host_addon_runtime",
+    directTenantImport: true
+  },
   {
     packageName: "@lucern/identity",
     role: "component_runtime",
@@ -5144,8 +5197,11 @@ function compactRecord(input) {
     Object.entries(input).filter(([, value]) => value !== void 0)
   );
 }
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 function recordValue(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return isRecord(value) ? value : {};
 }
 var createEvidenceProjection = defineProjection({
   contractName: "create_evidence",
@@ -5427,9 +5483,7 @@ function hasProvenance(input) {
 
 // ../contracts/src/lens-filter.contract.ts
 function isLensFilterCriteria(value) {
-  if (!value || typeof value !== "object") return false;
-  const obj = value;
-  return typeof obj.version === "number" && typeof obj.kind === "string";
+  return isRecord2(value) && typeof value.version === "number" && typeof value.kind === "string";
 }
 function isTaxonomyFilterCriteriaV1(value) {
   if (!isLensFilterCriteria(value)) return false;
@@ -5458,6 +5512,9 @@ function validateFilterCriteria(value) {
     ]
   };
 }
+function isRecord2(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function validateTaxonomyFilterV1(criteria) {
   const errors = [];
   if (!Array.isArray(criteria.entityTypeFilters)) {
@@ -5919,9 +5976,16 @@ var ADD_WORKTREE = {
     },
     projectId: {
       type: "string",
-      description: "Legacy topicId alias"
+      description: "Legacy topicId alias or resolver hint"
+    },
+    topicId: {
+      type: "string",
+      description: "Optional topic scope hint for resolver validation"
+    },
+    topicHint: {
+      type: "string",
+      description: "Natural-language topic hint for automatic topic resolution"
     },
-    topicId: { type: "string", description: "Optional topic scope hint" },
     branchId: {
       type: "string",
       description: "The branch this worktree investigates"
@@ -6019,6 +6083,22 @@ var ADD_WORKTREE = {
       type: "string",
       description: "Optional domain pack whose shaping hooks should influence generated questions and tasks"
     },
+    tags: {
+      type: "array",
+      description: "Additional topic-resolution tags for the worktree"
+    },
+    touchedPaths: {
+      type: "array",
+      description: "File paths used as topic-resolution signals"
+    },
+    sourceRef: {
+      type: "string",
+      description: "Source reference used as a topic-resolution signal"
+    },
+    sourceKind: {
+      type: "string",
+      description: "Source kind used as a topic-resolution signal"
+    },
     campaign: {
       type: "number",
       description: "Top-level pipeline campaign number. Campaigns define the outer execution slice."
@@ -6056,7 +6136,7 @@ var ADD_WORKTREE = {
       description: "Timestamp when worktree metadata was last reconciled"
     }
   },
-  required: ["title", "topicId"],
+  required: ["title"],
   response: {
     description: "The created worktree",
     fields: {
@@ -7553,15 +7633,15 @@ var IDENTITY_WHOAMI = {
 };
 var COMPILE_CONTEXT = {
   name: "compile_context",
-  description: "Compile a focused reasoning context for a topic. Like `git log --graph --decorate` for the reasoning substrate \u2014 returns the canonical Pillar 3 context pack through the public API shape.",
+  description: "Compile a focused reasoning context. If topicId is omitted, Lucern resolves the best topic from the query. Like `git log --graph --decorate` for the reasoning substrate \u2014 returns the canonical Pillar 3 context pack through the public API shape.",
   parameters: {
     topicId: {
       type: "string",
-      description: "Topic scope ID to compile"
+      description: "Optional topic scope ID. Omit to resolve the topic from query."
     },
     query: {
       type: "string",
-      description: "Optional focus query used to rank context items"
+      description: "Focus query used to resolve the topic and rank context items. Required when topicId is omitted."
     },
     budget: {
       type: "number",
@@ -7585,7 +7665,7 @@ var COMPILE_CONTEXT = {
       description: "Include related ontological entities in the compiled result"
     }
   },
-  required: ["topicId"],
+  required: [],
   response: {
     description: "Compiled context pack for the requested topic",
     fields: {
@@ -7759,18 +7839,60 @@ var CREATE_TASK = {
   name: "create_task",
   description: "Create an execution task tied to the reasoning state. Like `git task` \u2014 tracks concrete work items (calls to make, data to gather, analyses to run) linked to questions, beliefs, or worktrees.",
   parameters: {
-    title: { type: "string", description: "Task description" },
+    title: { type: "string", description: "Task title" },
     topicId: { type: "string", description: "Topic scope" },
+    description: {
+      type: "string",
+      description: "Long-form task description"
+    },
     taskType: {
       type: "string",
-      description: "Type: research, interview, analysis, data_collection",
-      enum: ["research", "interview", "analysis", "data_collection"]
+      description: "Task taxonomy",
+      enum: [
+        "general",
+        "find_evidence",
+        "verify_claim",
+        "research",
+        "review",
+        "interview",
+        "analysis",
+        "track_metrics"
+      ]
+    },
+    priority: {
+      type: "string",
+      description: "Priority",
+      enum: ["urgent", "high", "medium", "low"]
+    },
+    status: {
+      type: "string",
+      description: "Initial status (defaults to todo)",
+      enum: ["todo", "in_progress", "blocked", "done"]
+    },
+    linkedWorktreeId: {
+      type: "string",
+      description: "Worktree this task belongs to"
+    },
+    linkedBeliefId: {
+      type: "string",
+      description: "Belief this task supports"
     },
     linkedQuestionId: {
       type: "string",
       description: "Question this task addresses"
     },
-    linkedWorktreeId: { type: "string", description: "Worktree scope" }
+    assigneeId: {
+      type: "string",
+      description: "Principal assigned to the task"
+    },
+    dueDate: {
+      type: "number",
+      description: "Due date as epoch milliseconds"
+    },
+    tags: {
+      type: "array",
+      description: "Free-form string tags"
+    }
   },
   required: ["title"],
   response: {
@@ -9853,9 +9975,7 @@ function mcpContractFromArgsSchema(base, args, contractName) {
     required: converted.filter(([, field]) => field.required).map(([fieldName]) => fieldName)
   };
 }
-function defineFunctionContract(contract) {
-  return contract;
-}
+var defineFunctionContract = (contract) => contract;
 function authUserId(context) {
   return context.userId ?? context.principalId ?? "lucern-agent";
 }
@@ -10009,6 +10129,9 @@ var observationContextArgs = z.object({
   limit: z.number().optional().describe("Maximum observations to return."),
   status: z.string().optional().describe("Observation status filter.")
 });
+function isRecord3(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 var observationInput = (input, context) => withUserId(
   compactRecord4({
     projectId: input.projectId,
@@ -10041,7 +10164,7 @@ var contextContracts = [
     path: "/context/compile",
     sdkNamespace: "context",
     sdkMethod: "compileContext",
-    summary: "Compile a focused reasoning context for a topic.",
+    summary: "Compile a focused reasoning context, resolving topic from query when omitted.",
     convex: {
       module: "contextCompiler",
       functionName: "compile",
@@ -10063,8 +10186,8 @@ var contextContracts = [
       kind: "mutation",
       inputProjection: observationInput,
       outputProjection: (output, input) => ({
-        ...output && typeof output === "object" ? output : {},
-        observationId: output && typeof output === "object" ? output.nodeId : void 0,
+        ...isRecord3(output) ? output : {},
+        observationId: isRecord3(output) ? output.nodeId : void 0,
         observationType: input.observationType
       })
     },
@@ -11545,10 +11668,11 @@ var worktreeDecisionGateInputSchema = z.object({
   decidedBy: z.string().optional().describe("Actor that decided the gate verdict.")
 }).passthrough().describe("Decision gate contract for worktree activation or exit.");
 var addWorktreeArgs = z.object({
-  title: z.string().optional().describe("Human-readable worktree name or objective."),
+  title: z.string().describe("Human-readable worktree name or objective."),
   name: z.string().optional().describe("Storage-name alias for callers that already use backend naming."),
-  topicId: z.string().describe("Primary topic scope for the worktree."),
-  projectId: z.string().optional().describe("Legacy topicId alias."),
+  topicId: z.string().optional().describe("Optional primary topic scope hint for resolver validation."),
+  projectId: z.string().optional().describe("Legacy topicId alias/hint."),
+  topicHint: z.string().optional().describe("Natural-language topic hint for automatic topic resolution."),
   branchId: z.string().optional().describe("Legacy branch identifier for compatibility with workflow callers."),
   objective: z.string().optional().describe("Reasoning objective this worktree is intended to resolve."),
   hypothesis: z.string().optional().describe("Testable claim this worktree investigates."),
@@ -11573,6 +11697,10 @@ var addWorktreeArgs = z.object({
   autoShape: z.boolean().optional().describe("Whether to invoke inquiry auto-shaping during creation."),
   autoFixPolicy: autoFixPolicyInputSchema.optional(),
   domainPackId: z.string().optional().describe("Domain pack whose shaping hooks should influence the worktree."),
+  tags: z.array(z.string()).optional().describe("Additional topic-resolution tags for the worktree."),
+  touchedPaths: z.array(z.string()).optional().describe("File paths used as topic-resolution signals."),
+  sourceRef: z.string().optional().describe("Source reference used as a topic-resolution signal."),
+  sourceKind: z.string().optional().describe("Source kind used as a topic-resolution signal."),
   campaign: z.number().optional().describe("Top-level pipeline campaign number."),
   lane: z.string().optional().describe("Campaign lane for the worktree."),
   laneOrderInCampaign: z.number().optional().describe("Ordering for this lane within its campaign."),
@@ -11902,8 +12030,46 @@ var worktreesContracts = [
     args: openPullRequestArgs
   })
 ];
-
-// ../contracts/src/function-registry/tasks.ts
+var taskPrioritySchema = z.enum(["urgent", "high", "medium", "low"]);
+var taskStatusSchema2 = z.enum(["todo", "in_progress", "blocked", "done"]);
+var taskTypeSchema = z.enum([
+  "general",
+  "find_evidence",
+  "verify_claim",
+  "research",
+  "review",
+  "interview",
+  "analysis",
+  "track_metrics"
+]);
+var createTaskArgs = z.object({
+  title: z.string().describe("Task title."),
+  topicId: z.string().optional().describe("Topic scope."),
+  description: z.string().optional().describe("Long-form task description."),
+  taskType: taskTypeSchema.optional().describe("Task taxonomy."),
+  priority: taskPrioritySchema.optional().describe("Priority. Defaults to medium when omitted by the server."),
+  status: taskStatusSchema2.optional().describe("Initial status. Defaults to todo."),
+  linkedWorktreeId: z.string().optional().describe("Worktree this task belongs to."),
+  linkedBeliefId: z.string().optional().describe("Belief this task supports."),
+  linkedQuestionId: z.string().optional().describe("Question this task addresses."),
+  assigneeId: z.string().optional().describe("Principal assigned to the task."),
+  dueDate: z.number().optional().describe("Due date as epoch milliseconds."),
+  tags: z.array(z.string()).optional().describe("Free-form tags.")
+});
+var createTaskInput = (input) => compactRecord4({
+  title: input.title,
+  topicId: input.topicId,
+  description: input.description,
+  taskType: input.taskType,
+  priority: input.priority ?? "medium",
+  status: input.status ?? "todo",
+  linkedWorktreeId: input.linkedWorktreeId,
+  linkedBeliefId: input.linkedBeliefId,
+  linkedQuestionId: input.linkedQuestionId,
+  assigneeId: input.assigneeId,
+  dueDate: input.dueDate,
+  tags: input.tags
+});
 var taskInput = (input) => compactRecord4({
   ...input,
   taskId: input.taskId ?? input.id
@@ -11935,8 +12101,10 @@ var tasksContracts = [
     convex: {
       module: "tasks",
       functionName: "create",
-      kind: "mutation"
-    }
+      kind: "mutation",
+      inputProjection: createTaskInput
+    },
+    args: createTaskArgs
   }),
   surfaceContract({
     name: "list_tasks",
@@ -13054,9 +13222,12 @@ var ALL_FUNCTION_CONTRACTS = [
   ...legacyContracts
 ];
 assertSurfaceCoverage(ALL_FUNCTION_CONTRACTS);
-new Map(
+var FUNCTION_CONTRACTS_BY_NAME = new Map(
   ALL_FUNCTION_CONTRACTS.map((contract) => [contract.name, contract])
 );
+FUNCTION_CONTRACTS_BY_NAME.get.bind(
+  FUNCTION_CONTRACTS_BY_NAME
+);
 
 // ../contracts/src/tenant-bootstrap-seed.contract.ts
 function isCopyableSeedRequirement(entry) {
@@ -13697,7 +13868,8 @@ function readLucernJson() {
       topicId: parsed.topicId,
       topicName: parsed.topicName
     };
-  } catch {
+  } catch (error) {
+    debugMcpError("Failed to read .lucern.json ambient context", error);
     return null;
   }
 }
@@ -13719,7 +13891,8 @@ function writeLucernJson(context) {
 `,
       "utf-8"
     );
-  } catch {
+  } catch (error) {
+    debugMcpError("Failed to write .lucern.json ambient context", error);
   }
 }
 function isNonEmptyString(value) {
@@ -13761,15 +13934,25 @@ async function tryGetTopicById(topicId) {
     return null;
   }
   try {
-    return unwrapGatewayData(await getLucernClient().topics.get(normalizedTopicId));
-  } catch {
+    return unwrapGatewayData(
+      await getLucernClient().topics.get(normalizedTopicId)
+    );
+  } catch (error) {
+    debugMcp("Failed to load topic by id", {
+      topicId,
+      error: formatUnknownError(error)
+    });
     return null;
   }
 }
 async function tryGetNodeById(nodeId) {
   try {
     return unwrapGatewayData(await getLucernClient().nodes.get({ nodeId }));
-  } catch {
+  } catch (error) {
+    debugMcp("Failed to load node by id", {
+      nodeId,
+      error: formatUnknownError(error)
+    });
     return null;
   }
 }
@@ -13778,8 +13961,14 @@ async function findTopicByMappedProjectId(legacyScopeId) {
     const response = await getLucernClient().topics.list({});
     const data = unwrapGatewayData(response);
     const topics2 = Array.isArray(data?.topics) ? data.topics : Array.isArray(data?.items) ? data.items : [];
-    return topics2.find((topic) => readTopicMappedProjectId(topic) === legacyScopeId) || null;
-  } catch {
+    return topics2.find(
+      (topic) => readTopicMappedProjectId(topic) === legacyScopeId
+    ) || null;
+  } catch (error) {
+    debugMcp("Failed to resolve topic by mapped project id", {
+      legacyScopeId,
+      error: formatUnknownError(error)
+    });
     return null;
   }
 }
@@ -13789,17 +13978,9 @@ async function resolveTopicScopeId(scopeId, toolName) {
   if (!isNonEmptyString(scopeId)) {
     if (isNonEmptyString(defaultTopicId)) {
       resolved = defaultTopicId;
-    } else {
-      const lucernContext = readLucernJson();
-      const ambientTopicId = decodePublicTopicId(lucernContext?.topicId);
-      if (isNonEmptyString(ambientTopicId)) {
-        resolved = ambientTopicId;
-      }
     }
     if (!resolved) {
-      throw new Error(
-        `[${toolName}] Missing topic scope. Provide topicId.`
-      );
+      throw new Error(`[${toolName}] Missing topic scope. Provide topicId.`);
     }
   }
   if (!resolved) {
@@ -14017,28 +14198,30 @@ function readString2(value) {
 function readNullableNumber(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function isRecord4(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
 function refreshLucernContextFromBuildSession(payload, args) {
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+  if (!isRecord4(payload)) {
     return;
   }
-  const record = payload;
-  const topicId = readString2(record.topicId);
-  const worktreeId = readString2(record.worktreeId) ?? readString2(args.worktreeId);
+  const topicId = readString2(payload.topicId);
+  const worktreeId = readString2(payload.worktreeId) ?? readString2(args.worktreeId);
   if (!topicId || !worktreeId) {
     return;
   }
   writeLucernJson({
     topicId,
-    topicName: readString2(record.topicName),
+    topicName: readString2(payload.topicName),
     activeWorktree: {
       worktreeId,
-      title: readString2(record.worktreeName) ?? readString2(record.title) ?? readString2(record.name) ?? worktreeId,
-      status: readString2(record.status) ?? "unknown",
-      campaign: readNullableNumber(record.campaign),
-      lane: readString2(record.lane) ?? null,
-      orderInLane: readNullableNumber(record.orderInLane),
-      gate: readString2(record.gate) ?? null,
-      branch: readString2(record.branch) ?? readString2(args.branch) ?? null
+      title: readString2(payload.worktreeName) ?? readString2(payload.title) ?? readString2(payload.name) ?? worktreeId,
+      status: readString2(payload.status) ?? "unknown",
+      campaign: readNullableNumber(payload.campaign),
+      lane: readString2(payload.lane) ?? null,
+      orderInLane: readNullableNumber(payload.orderInLane),
+      gate: readString2(payload.gate) ?? null,
+      branch: readString2(payload.branch) ?? readString2(args.branch) ?? null
     }
   });
 }
@@ -14252,9 +14435,8 @@ var edgeHandlers = {
 
 // ../../apps/mcp-server/src/handlers/graph.ts
 var graphHandlers = {
-  async traverse_graph(args, ctx) {
-    return edgeHandlers.traverse_graph(args, ctx);
-  },
+  // Backward-compatible alias to keep the graph transport API stable.
+  traverse_graph: edgeHandlers.traverse_graph,
   async search_beliefs(args, ctx) {
     const topicId = await resolveTopicScopeId(
       readTopicIdArg(args),
@@ -14270,17 +14452,19 @@ var graphHandlers = {
       })
     );
   },
-  async find_contradictions(args, ctx) {
-    return contradictionHandlers.find_contradictions(args, ctx);
-  },
-  async bisect_confidence(args, ctx) {
-    return beliefHandlers.bisect_confidence(args, ctx);
-  },
+  // Backward-compatible alias to keep the graph transport API stable.
+  find_contradictions: contradictionHandlers.find_contradictions,
+  // Backward-compatible alias to keep the graph transport API stable.
+  bisect_confidence: beliefHandlers.bisect_confidence,
   async trace_entity_impact(args, ctx) {
-    const topicId = await resolveTopicScopeId(
-      readTopicIdArg(args),
-      "trace_entity_impact"
-    ).catch(() => void 0);
+    let topicId;
+    try {
+      topicId = await resolveTopicScopeId(
+        readTopicIdArg(args),
+        "trace_entity_impact"
+      );
+    } catch (error) {
+    }
     return formatSdkResult(
       await getSdkClient(ctx).graph.traceEntityImpact({
         nodeId: typeof args.nodeId === "string" ? args.nodeId : "",
@@ -15437,6 +15621,42 @@ var api = makeProxy("api");
 makeProxy("components");
 makeProxy("internal");
 
+// ../server-core/src/debug.ts
+function formatUnknownError2(error) {
+  if (error instanceof Error) {
+    const cause = error.cause;
+    const message = `${error.name}: ${error.message}`;
+    if (cause === void 0) {
+      return message;
+    }
+    return `${message}; cause=${formatUnknownError2(cause)}`;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error === null) {
+    return "null";
+  }
+  if (error === void 0) {
+    return "undefined";
+  }
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return Object.prototype.toString.call(error);
+  }
+}
+function isServerCoreFallbackDebugEnabled() {
+  const env = globalThis.process?.env;
+  return env?.LUCERN_COMPAT_FALLBACK_DEBUG === "1" || env?.LUCERN_SERVER_CORE_DEBUG === "1";
+}
+function debugServerCoreFallback(scope, message, context) {
+  if (!isServerCoreFallbackDebugEnabled()) {
+    return;
+  }
+  console.debug(`[${scope}] ${message}`, context ?? {});
+}
+
 // ../server-core/src/mcp-context-tools.ts
 function requireMcpConvex(authContext, label) {
   const convex = authContext.convex;
@@ -15449,6 +15669,9 @@ function requireMcpConvex(authContext, label) {
 // ../server-core/src/topic-resolver.ts
 var DEFAULT_THRESHOLD = 0.35;
 var TREE_MAX_DEPTH = 20;
+var BM25_K1 = 1.2;
+var BM25_B = 0.75;
+var BM25_NORMALIZATION = 8;
 var METADATA_TOKEN_KEYS = [
   "aliases",
   "alias",
@@ -15501,35 +15724,44 @@ function readStringArray2(value) {
   }
   return value.map((entry) => readString3(entry)).filter((entry) => Boolean(entry));
 }
+function isRecord5(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function decodePrefixedIdOrNull(value) {
+  const normalized = value.trim();
+  const match = /^([a-z][a-z0-9]*)_(.+)$/.exec(normalized);
+  if (!match) {
+    return null;
+  }
+  return {
+    prefix: match[1],
+    value: match[2]
+  };
+}
 function asRecord2(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  return isRecord5(value) ? value : {};
 }
 function normalizeTopicId(value) {
   const normalized = readString3(value);
   if (!normalized) {
     return void 0;
   }
-  try {
-    const decoded = decodePrefixedId(normalized);
-    return decoded.prefix === "top" ? decoded.value : normalized;
-  } catch {
-    return normalized;
-  }
+  const decoded = decodePrefixedIdOrNull(normalized);
+  return decoded?.prefix === "top" ? decoded.value : normalized;
 }
 function normalizeExternalId(value, prefix) {
   const normalized = readString3(value);
   if (!normalized) {
     return void 0;
   }
-  try {
-    const decoded = decodePrefixedId(normalized);
-    if (prefix && decoded.prefix !== prefix) {
-      return normalized;
-    }
-    return decoded.value;
-  } catch {
+  const decoded = decodePrefixedIdOrNull(normalized);
+  if (!decoded) {
     return normalized;
   }
+  if (decoded.prefix !== prefix) {
+    return normalized;
+  }
+  return decoded.value;
 }
 function normalizeToken(value) {
   const normalized = value.toLowerCase().trim();
@@ -15608,15 +15840,83 @@ function collectTopicMetadataTokens(metadata) {
 function topicNameSlug(name) {
   return tokenize(name).join(" ");
 }
+function topicTokenList(topic) {
+  return [
+    ...tokenize(topic.name),
+    ...tokenize(topic.description),
+    ...tokenize(topic.type),
+    ...collectTopicMetadataTokens(topic.metadata ?? {}).flatMap(
+      (value) => tokenize(value)
+    )
+  ];
+}
 function topicTokenSet(topic) {
   const tokens = /* @__PURE__ */ new Set();
-  addTokens(tokens, tokenize(topic.name));
-  addTokens(tokens, tokenize(topic.description));
-  addTokens(tokens, tokenize(topic.type));
-  addTokens(tokens, collectTopicMetadataTokens(topic.metadata ?? {}));
+  addTokens(tokens, topicTokenList(topic));
   return tokens;
 }
+function buildTopicScoreCorpus(topics2) {
+  const documentFrequencyByToken = /* @__PURE__ */ new Map();
+  let documentCount = 0;
+  let totalLength = 0;
+  for (const topic of topics2) {
+    const tokens = topicTokenList(topic);
+    const uniqueTokens = new Set(tokens);
+    documentCount += 1;
+    totalLength += tokens.length;
+    for (const token of uniqueTokens) {
+      documentFrequencyByToken.set(
+        token,
+        (documentFrequencyByToken.get(token) ?? 0) + 1
+      );
+    }
+  }
+  return {
+    documentCount,
+    averageDocumentLength: documentCount > 0 ? Math.max(1, totalLength / documentCount) : 1,
+    documentFrequencyByToken
+  };
+}
+function countTokens(tokens) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    counts.set(token, (counts.get(token) ?? 0) + 1);
+  }
+  return counts;
+}
+function bm25Score(topic, signals, corpus) {
+  if (signals.allTokens.size === 0 || corpus.documentCount === 0) {
+    return 0;
+  }
+  const documentTokens = topicTokenList(topic);
+  if (documentTokens.length === 0) {
+    return 0;
+  }
+  const counts = countTokens(documentTokens);
+  const docLength = documentTokens.length;
+  let score = 0;
+  for (const token of signals.allTokens) {
+    const termFrequency = counts.get(token) ?? 0;
+    if (termFrequency === 0) {
+      continue;
+    }
+    const documentFrequency = corpus.documentFrequencyByToken.get(token) ?? 0;
+    const idf = Math.log(
+      1 + (corpus.documentCount - documentFrequency + 0.5) / (documentFrequency + 0.5)
+    );
+    const denominator = termFrequency + BM25_K1 * (1 - BM25_B + BM25_B * (docLength / corpus.averageDocumentLength));
+    score += idf * (termFrequency * (BM25_K1 + 1) / denominator);
+  }
+  return score / (score + BM25_NORMALIZATION);
+}
 function scoreTopicMatch(topic, input) {
+  return scoreTopicMatchWithCorpus(
+    topic,
+    input,
+    buildTopicScoreCorpus([topic])
+  );
+}
+function scoreTopicMatchWithCorpus(topic, input, corpus) {
   const signals = buildSignalBag(input);
   const topicTokens = topicTokenSet(topic);
   if (signals.allTokens.size === 0 || topicTokens.size === 0) {
@@ -15630,6 +15930,7 @@ function scoreTopicMatch(topic, input) {
   }
   const union = (/* @__PURE__ */ new Set([...signals.allTokens, ...topicTokens])).size;
   const jaccard = union > 0 ? intersection / union : 0;
+  const bm25 = bm25Score(topic, signals, corpus);
   const topicSlug = topicNameSlug(topic.name);
   let boost = 0;
   for (const token of signals.tagTokens) {
@@ -15650,7 +15951,7 @@ function scoreTopicMatch(topic, input) {
       break;
     }
   }
-  return Math.max(0, Math.min(1, jaccard + boost));
+  return Math.max(0, Math.min(1, bm25 * 0.55 + jaccard * 0.45 + boost));
 }
 function normalizeTopicCandidate(value) {
   const record = asRecord2(value);
@@ -15672,26 +15973,21 @@ function normalizeTopicCandidate(value) {
     globalId: readString3(record.globalId)
   };
 }
-function topicMatchesScope(topic, tenantId, workspaceId) {
-  if (topic.status === "archived") {
-    return false;
-  }
-  if (tenantId && topic.tenantId && topic.tenantId !== tenantId) {
-    return false;
-  }
-  if (workspaceId && topic.workspaceId && topic.workspaceId !== workspaceId) {
-    return false;
-  }
-  return true;
-}
 async function fetchTopicById(ctx, topicId) {
   const normalizedTopicId = normalizeTopicId(topicId);
   if (!normalizedTopicId) {
     return null;
   }
-  const topic = await getConvex(ctx).query(api.topics.get, {
-    id: normalizedTopicId
-  }).catch(() => null);
+  let topic = null;
+  try {
+    topic = await getConvex(ctx).query(api.topics.get, {
+      id: normalizedTopicId
+    });
+  } catch (error) {
+    debugServerCoreFallback("topic-resolver", `fetchTopicById: topics.get(${normalizedTopicId})`, {
+      error: formatUnknownError2(error)
+    });
+  }
   return normalizeTopicCandidate(topic);
 }
 function readRecordTopicId(value) {
@@ -15701,7 +15997,14 @@ function readRecordTopicId(value) {
   );
 }
 async function fetchRecordTopicId(ctx, reference, args) {
-  const result = await getConvex(ctx).query(reference, args).catch(() => null);
+  let result = null;
+  try {
+    result = await getConvex(ctx).query(reference, args);
+  } catch (error) {
+    debugServerCoreFallback("topic-resolver", "fetchRecordTopicId", {
+      error: formatUnknownError2(error)
+    });
+  }
   return readRecordTopicId(result);
 }
 async function resolveBeliefTopicId(ctx, beliefId) {
@@ -15722,7 +16025,9 @@ async function resolveCommonBeliefTopicId(ctx, beliefIds) {
     return void 0;
   }
   const resolvedTopicIds = (await Promise.all(
-    normalizedBeliefIds.map((beliefId) => resolveBeliefTopicId(ctx, beliefId))
+    normalizedBeliefIds.map(
+      (beliefId) => resolveBeliefTopicId(ctx, beliefId)
+    )
   )).filter((topicId) => Boolean(topicId));
   if (resolvedTopicIds.length !== normalizedBeliefIds.length) {
     return void 0;
@@ -15731,17 +16036,31 @@ async function resolveCommonBeliefTopicId(ctx, beliefIds) {
 }
 async function fetchTopicTree(ctx) {
   const convex = getConvex(ctx);
-  const tree = await convex.query(api.topics.getTree, {
-    rootId: ROOT_TOPIC_ID,
-    maxDepth: TREE_MAX_DEPTH
-  }).catch(() => null);
+  let tree = null;
+  try {
+    tree = await convex.query(api.topics.getTree, {
+      rootId: ROOT_TOPIC_ID,
+      maxDepth: TREE_MAX_DEPTH
+    });
+  } catch (error) {
+    debugServerCoreFallback("topic-resolver", "fetchTopicTree: topics.getTree", {
+      error: formatUnknownError2(error)
+    });
+  }
   const normalizedTree = Array.isArray(tree) ? tree.map((topic) => normalizeTopicCandidate(topic)).filter((topic) => Boolean(topic)) : [];
   if (normalizedTree.length > 0) {
     return normalizedTree;
   }
-  const listed = await convex.query(api.topics.list, {
-    status: "active"
-  }).catch(() => []);
+  let listed = [];
+  try {
+    listed = await convex.query(api.topics.list, {
+      status: "active"
+    });
+  } catch (error) {
+    debugServerCoreFallback("topic-resolver", "fetchTopicTree: topics.list fallback", {
+      error: formatUnknownError2(error)
+    });
+  }
   return Array.isArray(listed) ? listed.map((topic) => normalizeTopicCandidate(topic)).filter((topic) => Boolean(topic)) : [];
 }
 function buildTopicMaps(topics2) {
@@ -15774,42 +16093,43 @@ function buildPath(topicId, byId) {
 function titleCase(value) {
   return value.replace(/\b[a-z]/g, (match) => match.toUpperCase());
 }
-function compactWhitespace(value) {
-  return value.replace(/\s+/g, " ").trim();
-}
 function deriveTopicName(input, parentTopic) {
   const textualHint = readString3(input.topicHint);
   if (textualHint && tokenize(textualHint).length > 0) {
-    return titleCase(compactWhitespace(textualHint)).slice(0, 60);
+    return titleCase(textualHint.replace(/\s+/g, " ").trim()).slice(0, 60);
   }
   const firstTag = (input.tags ?? []).find((tag) => tokenize(tag).length > 0);
   if (firstTag) {
-    return titleCase(compactWhitespace(firstTag)).slice(0, 60);
+    return titleCase(firstTag.replace(/\s+/g, " ").trim()).slice(0, 60);
   }
   const firstPathStem = (input.touchedPaths ?? []).map((filePath) => basenameStem(filePath)).find((stem) => stem && tokenize(stem).length > 0);
   if (firstPathStem) {
-    return titleCase(compactWhitespace(firstPathStem.replace(/[-_]+/g, " "))).slice(0, 60);
+    return titleCase(
+      firstPathStem.replace(/[-_]+/g, " ").replace(/\s+/g, " ").trim()
+    ).slice(0, 60);
   }
-  const summary = compactWhitespace(input.summary);
+  const summary = input.summary.replace(/\s+/g, " ").trim();
   if (summary.length > 0) {
     return titleCase(summary.slice(0, 60));
   }
   const sourceRef = readString3(input.sourceRef);
   if (sourceRef) {
-    return titleCase(compactWhitespace(sourceRef.replace(/[-_:/]+/g, " "))).slice(0, 60);
+    return titleCase(
+      sourceRef.replace(/[-_:/]+/g, " ").replace(/\s+/g, " ").trim()
+    ).slice(0, 60);
   }
-  return `${titleCase(parentTopic.name)} Subtopic`;
+  return parentTopic ? `${titleCase(parentTopic.name)} Subtopic` : "Lucern";
 }
-async function createChildTopic(ctx, parentTopic, input) {
+async function createTopic(ctx, input, parentTopic) {
   const convex = getConvex(ctx);
   const desiredTenantId = ctx.tenantId;
   const desiredWorkspaceId = readString3(input.workspaceId) ?? ctx.workspaceId;
   const createdBy = ctx.principalId ?? ctx.userId;
   const created = await convex.mutation(api.topics.create, {
     name: deriveTopicName(input, parentTopic),
-    description: compactWhitespace(input.summary).slice(0, 280) || void 0,
+    description: input.summary.replace(/\s+/g, " ").trim().slice(0, 280) || void 0,
     type: "theme",
-    parentTopicId: parentTopic.rawId,
+    ...parentTopic ? { parentTopicId: parentTopic.rawId } : {},
     tenantId: desiredTenantId,
     workspaceId: desiredWorkspaceId,
     visibility: "team",
@@ -15826,10 +16146,18 @@ async function createChildTopic(ctx, parentTopic, input) {
   const createdId = readString3(createdRecord.id) ?? readString3(createdRecord.topicId) ?? readString3(createdRecord._id);
   const hydrated = await fetchTopicById(ctx, createdId);
   if (!hydrated) {
-    throw new Error("[topic-resolver] Auto-created topic could not be reloaded.");
+    throw new Error(
+      "[topic-resolver] Auto-created topic could not be reloaded."
+    );
   }
   return hydrated;
 }
+function createChildTopic(ctx, parentTopic, input) {
+  return createTopic(ctx, input, parentTopic);
+}
+function createRootTopic(ctx, input) {
+  return createTopic(ctx, input);
+}
 function pushTrace(trace, topic, score) {
   const existing = trace[trace.length - 1];
   if (existing?.topicId === topic.rawId) {
@@ -15844,9 +16172,10 @@ function pushTrace(trace, topic, score) {
   });
 }
 function pickBestTopic(topics2, input) {
+  const corpus = buildTopicScoreCorpus(topics2);
   const ranked = topics2.filter((topic) => topic.status !== "archived").map((topic) => ({
     topic,
-    score: scoreTopicMatch(topic, input)
+    score: scoreTopicMatchWithCorpus(topic, input, corpus)
   })).sort((left, right) => {
     if (right.score !== left.score) {
       return right.score - left.score;
@@ -15862,27 +16191,31 @@ function pickFallbackRootTopic(topics2, input) {
   return pickBestTopic(parentless, input) ?? pickBestTopic(topics2, input);
 }
 async function loadTopicUniverse(ctx, input) {
-  const desiredTenantId = ctx.tenantId;
-  const desiredWorkspaceId = readString3(input.workspaceId) ?? ctx.workspaceId;
   const rawTopics = await fetchTopicTree(ctx);
-  const scopedTopics = rawTopics.filter(
-    (topic) => topicMatchesScope(topic, desiredTenantId, desiredWorkspaceId)
-  );
-  const root = rawTopics.find((topic) => topic.rawId === ROOT_TOPIC_ID) ?? await fetchTopicById(ctx, ROOT_TOPIC_ID) ?? pickFallbackRootTopic(scopedTopics, input) ?? null;
+  let candidatePool = rawTopics;
+  let root = pickFallbackRootTopic(candidatePool, input) ?? candidatePool.find((topic) => !topic.parentTopicId) ?? candidatePool[0] ?? null;
+  let rootCreated = false;
   if (!root) {
-    throw new Error("[topic-resolver] Root topic not found.");
+    if (input.autoCreate === false) {
+      throw new Error(
+        "[topic-resolver] No topics available for resolution."
+      );
+    }
+    root = await createRootTopic(ctx, input);
+    rootCreated = true;
+    candidatePool = [root];
   }
-  const topics2 = rawTopics.filter(
-    (topic) => topic.rawId === root.rawId || topicMatchesScope(topic, desiredTenantId, desiredWorkspaceId)
-  );
   const dedupedTopics = /* @__PURE__ */ new Map();
   dedupedTopics.set(root.rawId, root);
-  for (const topic of topics2) {
+  for (const topic of candidatePool) {
     dedupedTopics.set(topic.rawId, topic);
   }
-  const { byId, childrenByParent } = buildTopicMaps([...dedupedTopics.values()]);
+  const { byId, childrenByParent } = buildTopicMaps([
+    ...dedupedTopics.values()
+  ]);
   return {
     root,
+    rootCreated,
     byId,
     childrenByParent
   };
@@ -15893,7 +16226,9 @@ async function validateTopicOrNull(ctx, topicId) {
     return null;
   }
   const { byId } = await loadTopicUniverse(ctx, {
-    summary: topic.name});
+    summary: topic.name,
+    autoCreate: false
+  });
   if (!byId.has(topic.rawId)) {
     byId.set(topic.rawId, topic);
   }
@@ -15915,8 +16250,10 @@ async function resolveTopicForWrite(ctx, input) {
   const threshold = typeof input.threshold === "number" && Number.isFinite(input.threshold) ? Math.max(0, Math.min(1, input.threshold)) : DEFAULT_THRESHOLD;
   const createThreshold = Math.max(0.5, Math.min(1, threshold + 0.15));
   const autoCreate = input.autoCreate !== false;
-  const { root, byId, childrenByParent } = await loadTopicUniverse(ctx, input);
+  const { root, rootCreated, byId, childrenByParent } = await loadTopicUniverse(ctx, input);
   const trace = [];
+  const scoreCorpus = buildTopicScoreCorpus(byId.values());
+  const scoreTopic = (topic) => scoreTopicMatchWithCorpus(topic, input, scoreCorpus);
   const ownScore = /* @__PURE__ */ new Map();
   const subtreeScore = /* @__PURE__ */ new Map();
   const computeSubtreeScore = (topicId, visited) => {
@@ -15933,7 +16270,7 @@ async function resolveTopicForWrite(ctx, input) {
       return 0;
     }
     if (!ownScore.has(topicId)) {
-      ownScore.set(topicId, scoreTopicMatch(topic, input));
+      ownScore.set(topicId, scoreTopic(topic));
     }
     let best = ownScore.get(topicId);
     for (const child of childrenByParent.get(topicId) ?? []) {
@@ -15945,7 +16282,7 @@ async function resolveTopicForWrite(ctx, input) {
   };
   computeSubtreeScore(root.rawId, /* @__PURE__ */ new Set());
   let current = root;
-  let currentScore = ownScore.get(root.rawId) ?? scoreTopicMatch(root, input);
+  let currentScore = ownScore.get(root.rawId) ?? scoreTopic(root);
   pushTrace(trace, current, currentScore);
   while (true) {
     const children = (childrenByParent.get(current.rawId) ?? []).filter(
@@ -15956,7 +16293,7 @@ async function resolveTopicForWrite(ctx, input) {
     }
     const rankedChildren = children.map((topic) => {
       if (!ownScore.has(topic.rawId)) {
-        ownScore.set(topic.rawId, scoreTopicMatch(topic, input));
+        ownScore.set(topic.rawId, scoreTopic(topic));
       }
       return {
         topic,
@@ -15968,13 +16305,13 @@ async function resolveTopicForWrite(ctx, input) {
       break;
     }
     current = bestChild.topic;
-    currentScore = ownScore.get(current.rawId) ?? scoreTopicMatch(current, input);
+    currentScore = ownScore.get(current.rawId) ?? scoreTopic(current);
     pushTrace(trace, current, currentScore);
   }
-  let created = false;
+  let created = rootCreated;
   let resolvedTopic = current;
   let finalScore = currentScore;
-  if (autoCreate && finalScore < createThreshold) {
+  if (autoCreate && !rootCreated && finalScore < createThreshold) {
     const siblings = childrenByParent.get(current.rawId) ?? [];
     const derivedName = deriveTopicName(input, current).toLowerCase();
     const existingSibling = siblings.find(
@@ -15982,7 +16319,7 @@ async function resolveTopicForWrite(ctx, input) {
     );
     if (existingSibling) {
       resolvedTopic = existingSibling;
-      finalScore = scoreTopicMatch(existingSibling, input);
+      finalScore = scoreTopic(existingSibling);
       pushTrace(trace, resolvedTopic, finalScore);
     } else {
       resolvedTopic = await createChildTopic(ctx, current, input);
@@ -16360,9 +16697,7 @@ var ontologyHandlers = {
 
 // ../../apps/mcp-server/src/handlers/ontology-matching.ts
 var ontologyMatchingHandlers = {
-  async match_entity_type(args, ctx) {
-    return ontologyHandlers.match_entity_type(args, ctx);
-  },
+  match_entity_type: ontologyHandlers.match_entity_type,
   async discover_entity_connections(args, ctx) {
     return formatSdkResult(
       await getSdkClient(ctx).context.discoverEntityConnections({
@@ -16539,20 +16874,30 @@ var researchVerificationHandlers = {
 function cleanString(value) {
   return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
 }
+function isRecord6(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
 function prefixId(prefix, value) {
   const cleaned = cleanString(value);
   if (!cleaned) {
     return `${prefix}_unknown`;
   }
-  try {
-    const decoded = decodePrefixedId(cleaned);
-    if (decoded.prefix === prefix) {
-      return cleaned;
-    }
-  } catch {
+  const decoded = tryDecodePrefixedId(cleaned);
+  if (decoded?.prefix === prefix) {
+    return cleaned;
   }
   return encodePrefixedId(prefix, cleaned);
 }
+function tryDecodePrefixedId(value) {
+  try {
+    return decodePrefixedId(value);
+  } catch (error) {
+    return ignorePrefixedIdDecodeFailure();
+  }
+}
+function ignorePrefixedIdDecodeFailure(_error) {
+  return void 0;
+}
 function mapSelectedIds(value) {
   return {
     invariants: (value.invariants ?? []).map((id) => prefixId("bel", id)),
@@ -16585,7 +16930,7 @@ function toPublicCompiledContext(pack) {
     scopedTopicIds: (pack.scopedTopicIds ?? []).map((id) => prefixId("top", id)),
     generatedAt: pack.generatedAt,
     ranking: pack.rankingProfile,
-    summary: pack.summary,
+    summary: isRecord6(pack.summary) ? pack.summary : {},
     invariants: (pack.invariants ?? []).map((belief) => ({
       beliefId: prefixId("bel", belief.nodeId),
       text: belief.canonicalText,
@@ -16635,7 +16980,7 @@ function toPublicCompiledContext(pack) {
         entityId: cleanString(entity.nodeId) ?? "",
         entityType: entity.entityType,
         title: entity.title,
-        text: cleanString(entity.canonicalText),
+        text: cleanString(entity.title),
         connectedBeliefCount: entity.connectedBeliefCount,
         connectedEvidenceCount: entity.connectedEvidenceCount,
         score: entity.score,
@@ -16656,7 +17001,7 @@ function toPublicCompiledContext(pack) {
         }))
       } : {}
     },
-    diagnostics: pack.diagnostics,
+    diagnostics: isRecord6(pack.diagnostics) ? pack.diagnostics : {},
     ...pack.compilationMode ? { compilationMode: pack.compilationMode } : {},
     ...pack.failureContext ? {
       failureContext: {
@@ -16687,10 +17032,20 @@ function toPublicCompiledContext(pack) {
 var scopeContextHandlers = {
   async compile_context(args, ctx) {
     const requestedScope = readTopicIdArg(args);
-    if (!requestedScope) {
-      throw new Error("[compile_context] topicId is required.");
-    }
-    const topicId = await resolveTopicScopeId(requestedScope, "compile_context");
+    const query = readString(args.query);
+    if (!requestedScope && !query) {
+      throw new Error("[compile_context] query is required when topicId is omitted.");
+    }
+    const topicId = requestedScope ? await resolveTopicScopeId(requestedScope, "compile_context") : (await resolveTopicForWrite(ctx, {
+      workspaceId: readString(args.workspaceId),
+      topicHint: readString(args.topicHint),
+      summary: query ?? "",
+      tags: readStringArray(args.tags),
+      touchedPaths: readStringArray(args.touchedPaths),
+      sourceRef: readString(args.sourceRef),
+      sourceKind: readString(args.sourceKind) ?? "compile_context",
+      autoCreate: false
+    })).topicId;
     if (ctx.sessionType === "user" && Array.isArray(ctx.allowedTopics) && (!ctx.allowedTopics.includes(topicId) || ctx.allowedTopics.length === 0)) {
       throw new Error(
         `[compile_context] Access denied to compile context for topic ${topicId}.`
@@ -17082,9 +17437,10 @@ var MUTATION_TOOL_NAMES = /* @__PURE__ */ new Set([
   "deprecate_ontology_version",
   "manage_write_policy"
 ]);
-function isMutationTool(toolName) {
-  return MUTATION_TOOL_NAMES.has(toolName);
-}
+var isMutationTool = (toolName) => {
+  const normalized = toolName.trim();
+  return normalized.length > 0 && MUTATION_TOOL_NAMES.has(normalized);
+};
 var sessionWritesBySession = /* @__PURE__ */ new Map();
 function recordWrite(toolName, topicId, sessionId = "default") {
   const record = {
@@ -17216,8 +17572,6 @@ async function checkWritePolicy(toolName, topicId, authCtx) {
     };
   }
 }
-
-// ../../apps/mcp-server/src/credentials.ts
 var LUCERN_HOME = path2.join(os.homedir(), ".lucern");
 path2.join(LUCERN_HOME, "credentials");