@lucern/events 1.0.11 → 1.0.12

package/dist/index.js

@@ -1456,6 +1456,59 @@ var REMOVE_LENS_FROM_TOPIC = {
   tier: "workhorse"
 };
 
+// ../contracts/src/tool-contracts.context-orientation.ts
+var LUCERN_ORIENT = {
+  name: "lucern_orient",
+  description: "Load the Lucern reasoning grammar before operating. Like `git help` plus a repository CONTRIBUTING guide for reasoning state - teaches the git-shaped model of topics, campaigns, lanes, worktrees, beliefs, questions, evidence, receipts, gates, and merges.",
+  parameters: {
+    audience: {
+      type: "string",
+      description: "Audience for the primer: agent, human, operator, or developer.",
+      enum: ["agent", "human", "operator", "developer"]
+    },
+    depth: {
+      type: "string",
+      description: "Orientation depth: quick, standard, or deep.",
+      enum: ["quick", "standard", "deep"]
+    },
+    situation: {
+      type: "string",
+      description: "Optional task or query context used to tailor suggested next calls."
+    },
+    includeExamples: {
+      type: "boolean",
+      description: "Whether to include concrete tool-call examples."
+    },
+    includeToolMap: {
+      type: "boolean",
+      description: "Whether to include situation-to-tool routing guidance."
+    },
+    includeFuture: {
+      type: "boolean",
+      description: "Whether to include future exemplar, gauntlet, and training-data capabilities."
+    }
+  },
+  required: [],
+  response: {
+    description: "Canonical operator primer for Lucern's git-shaped reasoning substrate.",
+    fields: {
+      schemaVersion: "string - lucern_orientation.v1",
+      canonicalMentalModel: "object - concise model of Lucern as git-shaped reasoning state",
+      workflow: "array - recommended branch -> investigate -> prove gate -> merge workflow",
+      grammarMap: "array - primitive-to-git-analogy map for topics, campaigns, worktrees, beliefs, questions, evidence, edges, contradictions, and gates",
+      firstMoves: "array - recommended first tools for a cold-start agent",
+      receiptRules: "array - how to interpret candidateCounts, broadening, coverageWarning, and noDefaultGlobalScan",
+      safetyRules: "array - mutation and completion rules that preserve reasoning lineage",
+      toolMap: "array | undefined - situation-to-tool routing map when requested",
+      examples: "array | undefined - concrete tool-call examples when requested",
+      suggestedNextCalls: "array - safe next tool calls for the current situation"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+
 // ../contracts/src/tool-contracts.ontology.ts
 var MANAGE_WRITE_POLICY = {
   name: "manage_write_policy",
@@ -3965,10 +4018,34 @@ var COMPILE_CONTEXT = {
       type: "string",
       description: "Optional source kind used as a resolver signal, such as cli, worktree, commit, or docs."
     },
+    campaign: {
+      type: "number",
+      description: "Optional campaign dimension seed. When supplied without topicId, the compiler fans out across all carrier topics for that campaign instead of resolving a single topic."
+    },
+    lane: {
+      type: "string",
+      description: "Optional lane dimension seed. When supplied without topicId, the compiler reads all matching worktrees and their carrier topics."
+    },
+    status: {
+      type: "string",
+      description: "Optional state/status dimension seed for worktrees and graph rows."
+    },
+    principalId: {
+      type: "string",
+      description: "Optional principal seed for work authored, touched, or owned by a human, agent, group, or service principal."
+    },
+    workspaceId: {
+      type: "string",
+      description: "Optional workspace seed used by hosted MCP and SDK clients when compiling tenant-scoped context."
+    },
     budget: {
       type: "number",
       description: "Token budget for prompt injection planning"
     },
+    tokenBudget: {
+      type: "number",
+      description: "Compatibility alias for budget. External MCP clients may send tokenBudget when requesting prompt injection planning."
+    },
     ranking: {
       type: "string",
       description: "Ranking profile for context ordering",
@@ -4659,6 +4736,7 @@ var MCP_TOOL_CONTRACTS = {
   update_worktree_metadata: UPDATE_WORKTREE_METADATA,
   identity_whoami: IDENTITY_WHOAMI,
   resolve_interactive_principal: RESOLVE_INTERACTIVE_PRINCIPAL,
+  lucern_orient: LUCERN_ORIENT,
   compile_context: COMPILE_CONTEXT,
   record_scope_learning: RECORD_SCOPE_LEARNING,
   pipeline_snapshot: PIPELINE_SNAPSHOT,
@@ -10504,6 +10582,20 @@ async function emitDomainEvent(invokeMutation, input) {
   return await invokeMutation("events:recordEvent", input);
 }
 
+// ../contracts/src/ids.contract.ts
+var PREFIXED_ID_PATTERN = /^([a-z][a-z0-9]*)_(.+)$/;
+function decodePrefixedId(id) {
+  const normalized = id.trim();
+  const match = PREFIXED_ID_PATTERN.exec(normalized);
+  if (!match) {
+    throw new Error(`Invalid prefixed ID: ${id}`);
+  }
+  return {
+    prefix: match[1],
+    value: match[2]
+  };
+}
+
 // ../contracts/src/schema-helpers/spine/tables/epistemicNodes.ts
 var NODE_TYPES = [
   "decision",
@@ -11666,15 +11758,57 @@ function isRecord(value) {
 function recordValue(value) {
   return isRecord(value) ? value : {};
 }
+function normalizeTopicIdForKernel(topicId) {
+  const normalized = topicId?.trim();
+  if (!normalized) {
+    return void 0;
+  }
+  try {
+    const decoded = decodePrefixedId(normalized);
+    return decoded.prefix === "top" ? decoded.value : normalized;
+  } catch {
+    return normalized;
+  }
+}
+function normalizeWorktreeId(value) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return void 0;
+  }
+  if (normalized.startsWith("wt_")) {
+    return normalized.slice("wt_".length);
+  }
+  return normalized;
+}
+function targetKind(targetId) {
+  const normalized = targetId?.trim();
+  if (!normalized) {
+    return "unknown";
+  }
+  if (normalized.startsWith("wt_") || /^tn[a-z0-9]+$/i.test(normalized)) {
+    return "worktree";
+  }
+  if (normalized.startsWith("que_")) {
+    return "question";
+  }
+  if (normalized.startsWith("bel_")) {
+    return "belief";
+  }
+  return "unknown";
+}
 var createEvidenceProjection = defineProjection({
   contractName: "create_evidence",
   inputSchema: createEvidenceInputSchema,
   project: (input) => {
     const text = input.text ?? input.canonicalText;
     const weight = typeof input.weight === "number" ? input.weight : void 0;
+    const target = input.targetId ?? input.targetNodeId;
+    const kind = targetKind(target);
+    const linkedWorktreeId = kind === "worktree" ? normalizeWorktreeId(target) : void 0;
+    const linkedBeliefNodeId = input.linkedBeliefNodeId ?? (kind === "belief" || kind === "unknown" ? input.targetNodeId ?? input.targetId : void 0);
     return compactRecord({
       projectId: input.projectId,
-      topicId: input.topicId,
+      topicId: normalizeTopicIdForKernel(input.topicId),
       text,
       title: input.title ?? text,
       content: input.content ?? text,
@@ -11693,11 +11827,13 @@ var createEvidenceProjection = defineProjection({
         source: input.source,
         targetId: input.targetId,
         targetNodeId: input.targetNodeId,
+        targetKind: kind === "unknown" ? void 0 : kind,
+        linkedWorktreeId,
         weight,
         reasoning: input.reasoning,
         rationale: input.rationale
       }),
-      linkedBeliefNodeId: input.linkedBeliefNodeId ?? input.targetNodeId ?? input.targetId,
+      linkedBeliefNodeId,
       evidenceRelation: input.evidenceRelation ?? (weight === void 0 ? void 0 : weight < 0 ? "contradicts" : "supports"),
       confidence: input.confidence ?? (weight === void 0 ? void 0 : Math.min(1, Math.max(0, Math.abs(weight)))),
       rationale: input.rationale,
@@ -12000,6 +12136,7 @@ function entries(names, surfaceClass, surfaceIntent, surfaces, rationale) {
   );
 }
 var MCP_CORE_OPERATION_NAMES = [
+  "lucern_orient",
   "compile_context",
   "identity_whoami",
   "resolve_interactive_principal",
@@ -12628,6 +12765,14 @@ var observationContextArgs = z.object({
   limit: z.number().optional().describe("Maximum observations to return."),
   status: z.string().optional().describe("Observation status filter.")
 });
+var lucernOrientArgs = z.object({
+  audience: z.enum(["agent", "human", "operator", "developer"]).optional().describe("Audience for the orientation primer."),
+  depth: z.enum(["quick", "standard", "deep"]).optional().describe("How much orientation detail to include."),
+  situation: z.string().optional().describe("Optional task or query context for suggested next calls."),
+  includeExamples: z.boolean().optional().describe("Include concrete tool-call examples."),
+  includeToolMap: z.boolean().optional().describe("Include situation-to-tool routing guidance."),
+  includeFuture: z.boolean().optional().describe("Include future training and pedagogy capabilities.")
+});
 function isRecord2(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -12655,6 +12800,20 @@ var observationInput = (input, context) => withUserId(
   context
 );
 var contextContracts = [
+  surfaceContract({
+    name: "lucern_orient",
+    kind: "query",
+    domain: "context",
+    surfaceClass: "platform_public",
+    path: "/context/orient",
+    sdkNamespace: "context",
+    sdkMethod: "lucernOrient",
+    summary: "Return the canonical Lucern operator orientation primer.",
+    gateway: {
+      handler: "context.lucernOrient"
+    },
+    args: lucernOrientArgs
+  }),
   surfaceContract({
     name: "compile_context",
     kind: "query",
@@ -13074,7 +13233,7 @@ var createEvidenceArgs = z.object({
   text: z.string().describe("Canonical evidence text."),
   source: z.string().optional().describe("Source URL or source label."),
   sourceUrl: z.string().optional().describe("Canonical source URL."),
-  targetId: z.string().optional().describe("Belief or question identifier to link immediately."),
+  targetId: z.string().optional().describe("Belief, question, or worktree identifier to link or preserve on the evidence record."),
   linkedBeliefNodeId: z.string().optional().describe("Belief node this evidence bears on."),
   evidenceRelation: evidenceRelationSchema.optional().describe("How the evidence relates to the linked belief."),
   confidence: z.number().optional().describe("Confidence in the evidence relation."),
@@ -13107,11 +13266,6 @@ var addEvidenceArgs = z.object({
   contentType: z.string().optional().describe("Content format or MIME hint."),
   metadata: jsonRecordSchema4.optional().describe("Optional metadata merged into the evidence node.")
 });
-var evidenceIdInput = (input) => compactRecord4({
-  evidenceId: input.evidenceId,
-  insightId: input.insightId,
-  nodeId: input.nodeId ?? input.id ?? input.evidenceId
-});
 var createEvidenceInput = (input, context) => {
   const parsed = createEvidenceProjection.inputSchema.safeParse(input);
   if (!parsed.success) {
@@ -13225,11 +13379,8 @@ var evidenceContracts = [
     sdkNamespace: "evidence",
     sdkMethod: "getEvidence",
     summary: "Get evidence.",
-    convex: {
-      module: "evidence",
-      functionName: "getById",
-      kind: "query",
-      inputProjection: evidenceIdInput
+    gateway: {
+      handler: "evidence.get"
     }
   }),
   surfaceContract({
@@ -13255,17 +13406,8 @@ var evidenceContracts = [
     sdkNamespace: "evidence",
     sdkMethod: "searchEvidence",
     summary: "Search evidence.",
-    convex: {
-      module: "nodes",
-      functionName: "search",
-      kind: "query",
-      inputProjection: (input) => compactRecord4({
-        searchQuery: input.searchQuery ?? input.q ?? input.query,
-        projectId: input.projectId,
-        topicId: input.topicId,
-        nodeType: "evidence",
-        limit: input.limit
-      })
+    gateway: {
+      handler: "evidence.search"
     }
   }),
   surfaceContract({
@@ -13853,10 +13995,8 @@ var topicsContracts = [
     sdkNamespace: "topics",
     sdkMethod: "getTopicGraphSpine",
     summary: "Verify topic nodes and parent-child graph edges.",
-    convex: {
-      module: "topics",
-      functionName: "getTopicGraphSpine",
-      kind: "query"
+    gateway: {
+      handler: "topics.graphSpine"
     },
     args: getTopicGraphSpineArgs
   })
@@ -15563,10 +15703,8 @@ var graphContracts = [
     sdkNamespace: "graphAnalysis",
     sdkMethod: "listGraphIntelligenceQueries",
     summary: "List Graph Intelligence query catalog entries.",
-    convex: {
-      module: "contextCompiler",
-      functionName: "listGraphIntelligenceQueries",
-      kind: "query"
+    gateway: {
+      handler: "graph.listIntelligenceQueries"
     },
     args: graphIntelligenceCatalogArgs
   }),