@lucern/contracts 1.0.10 → 1.0.12

package/dist/function-registry/context.d.ts

@@ -69,7 +69,7 @@ type FunctionConvexTarget = {
     outputProjection?: ContractOutputProjection;
 };
 type FunctionGatewayTarget = {
-    handler: "identity.whoami" | "beliefs.list" | "evidence.list" | "questions.list" | "worktrees.get" | "tasks.create" | "tasks.list" | "tasks.update" | "tasks.complete";
+    handler: "identity.whoami" | "beliefs.list" | "evidence.get" | "evidence.list" | "evidence.search" | "questions.list" | "worktrees.get" | "tasks.create" | "tasks.list" | "tasks.update" | "tasks.complete" | "context.lucernOrient" | "graph.listIntelligenceQueries" | "topics.graphSpine";
 };
 
 declare const contextContracts: readonly [{
@@ -100,7 +100,7 @@ declare const contextContracts: readonly [{
     };
     auth: {
         scopes: string[];
-        allowedPrincipalTypes: ("user" | "service" | "agent" | "group" | "external_viewer")[];
+        allowedPrincipalTypes: ("agent" | "user" | "service" | "group" | "external_viewer")[];
     };
     convex: FunctionConvexTarget | undefined;
     gateway: FunctionGatewayTarget | undefined;
@@ -140,7 +140,7 @@ declare const contextContracts: readonly [{
     };
     auth: {
         scopes: string[];
-        allowedPrincipalTypes: ("user" | "service" | "agent" | "group" | "external_viewer")[];
+        allowedPrincipalTypes: ("agent" | "user" | "service" | "group" | "external_viewer")[];
     };
     convex: FunctionConvexTarget | undefined;
     gateway: FunctionGatewayTarget | undefined;
@@ -180,7 +180,47 @@ declare const contextContracts: readonly [{
     };
     auth: {
         scopes: string[];
-        allowedPrincipalTypes: ("user" | "service" | "agent" | "group" | "external_viewer")[];
+        allowedPrincipalTypes: ("agent" | "user" | "service" | "group" | "external_viewer")[];
+    };
+    convex: FunctionConvexTarget | undefined;
+    gateway: FunctionGatewayTarget | undefined;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
+    openapi: {
+        summary: string;
+        tags: string[];
+    };
+}, {
+    name: string;
+    kind: FunctionKind;
+    idempotent: FunctionIdempotency;
+    effects: readonly FunctionEffect[];
+    invariants: readonly string[] | undefined;
+    surfaceIntent: FunctionSurfaceIntent;
+    domain: string;
+    surfaceClass: SurfaceClass;
+    surfaces: FunctionSurfaceMap;
+    replacedBy: string | undefined;
+    rest: {
+        method: "GET" | "POST" | "PATCH" | "DELETE";
+        path: string;
+    };
+    sdk: {
+        namespace: string;
+        method: string;
+    };
+    mcp: {
+        exposed: boolean;
+        toolName: string;
+    } & McpToolContract & {
+        exposed: boolean;
+        toolName: string;
+    };
+    auth: {
+        scopes: string[];
+        allowedPrincipalTypes: ("agent" | "user" | "service" | "group" | "external_viewer")[];
     };
     convex: FunctionConvexTarget | undefined;
     gateway: FunctionGatewayTarget | undefined;

package/dist/function-registry/context.js

@@ -1658,6 +1658,59 @@ var REMOVE_LENS_FROM_TOPIC = {
   tier: "workhorse"
 };
 
+// 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"
+};
+
 // src/tool-contracts.intelligence-evidence.ts
 var DETECT_CONFIRMATION_BIAS = {
   name: "detect_confirmation_bias",
@@ -2708,10 +2761,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",
@@ -4618,6 +4695,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,
@@ -4733,6 +4811,7 @@ function entries(names, surfaceClass, surfaceIntent, surfaces, rationale) {
   );
 }
 var MCP_CORE_OPERATION_NAMES = [
+  "lucern_orient",
   "compile_context",
   "identity_whoami",
   "resolve_interactive_principal",
@@ -5346,6 +5425,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 isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -5373,6 +5460,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",