@lucern/contracts 0.3.0-alpha.2 → 0.3.0-alpha.4

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

@@ -1,4 +1,4 @@
-import * as zod from 'zod';
+import { z } from 'zod';
 
 /**
  * MCP Tool Contract Definitions
@@ -115,10 +115,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -154,10 +154,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -193,10 +193,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -232,10 +232,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -271,10 +271,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -310,10 +310,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -349,10 +349,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -388,10 +388,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -427,10 +427,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -466,10 +466,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -505,10 +505,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -544,10 +544,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];
@@ -583,10 +583,10 @@ declare const graphContracts: readonly [{
         allowedPrincipalTypes: ("user" | "service" | "agent")[];
     };
     convex: FunctionConvexTarget | undefined;
-    args: zod.ZodTypeAny;
-    returns: zod.ZodTypeAny;
-    input: zod.ZodTypeAny;
-    output: zod.ZodTypeAny;
+    args: z.ZodTypeAny;
+    returns: z.ZodTypeAny;
+    input: z.ZodTypeAny;
+    output: z.ZodTypeAny;
     openapi: {
         summary: string;
         tags: string[];

package/dist/function-registry/graph.js

@@ -422,6 +422,14 @@ var ADD_WORKTREE = {
   description: "Check out a branch into an active worktree for investigation. Like `git worktree add <branch>` \u2014 creates independent working state on a thematic branch. Beliefs committed within the worktree can be freely amended (draft code on a feature branch). When investigation is complete, `merge` integrates findings into main.",
   parameters: {
     title: { type: "string", description: "Worktree name/objective" },
+    name: {
+      type: "string",
+      description: "Optional storage-name alias for callers that already use backend naming"
+    },
+    projectId: {
+      type: "string",
+      description: "Legacy topicId alias"
+    },
     topicId: { type: "string", description: "Optional topic scope hint" },
     branchId: {
       type: "string",
@@ -435,14 +443,87 @@ var ADD_WORKTREE = {
       type: "string",
       description: "The testable claim this worktree investigates"
     },
+    rationale: {
+      type: "string",
+      description: "Why this worktree exists and why it belongs in the campaign"
+    },
+    worktreeType: {
+      type: "string",
+      description: "Schema-enum worktree type used by the kernel lifecycle and retrieval layers"
+    },
+    gate: {
+      type: "string",
+      description: "Exit gate name for this worktree"
+    },
+    startDate: {
+      type: "number",
+      description: "Planned start timestamp in milliseconds since epoch"
+    },
+    endDate: {
+      type: "number",
+      description: "Planned end timestamp in milliseconds since epoch"
+    },
+    durationWeeks: {
+      type: "number",
+      description: "Planned duration in weeks"
+    },
+    confidenceImpact: {
+      type: "string",
+      description: "Expected confidence impact if the worktree succeeds",
+      enum: ["high", "medium", "low"]
+    },
+    beliefFocus: {
+      type: "string",
+      description: "Natural-language focus spanning the target belief neighborhood"
+    },
     beliefIds: {
       type: "array",
-      description: "Beliefs to test in this worktree"
+      description: "Legacy alias for targetBeliefIds"
+    },
+    beliefs: {
+      type: "array",
+      description: "Legacy alias for targetBeliefIds"
+    },
+    targetBeliefIds: {
+      type: "array",
+      description: "Belief node IDs this worktree is expected to test or update"
+    },
+    targetQuestionIds: {
+      type: "array",
+      description: "Question node IDs this worktree is expected to answer"
+    },
+    keyQuestions: {
+      type: "array",
+      description: "Inline key question objects with question, optional status, answer, answerConfidence, and linkedQuestionId"
+    },
+    evidenceSignals: {
+      type: "array",
+      description: "Evidence signal objects with signal, optional collected state, progress, and notes"
+    },
+    decisionGate: {
+      type: "object",
+      description: "Decision gate object with goCriteria, noGoSignals, optional verdict, rationale, decidedAt, and decidedBy"
+    },
+    goCriteria: {
+      type: "array",
+      description: "Shorthand go criteria used to build decisionGate"
+    },
+    noGoSignals: {
+      type: "array",
+      description: "Shorthand no-go signals used to build decisionGate"
+    },
+    proofArtifacts: {
+      type: "array",
+      description: "Expected proof artifacts required to close the worktree"
     },
     autoShape: {
       type: "boolean",
       description: "Whether to invoke inquiry auto-shaping during worktree creation"
     },
+    autoFixPolicy: {
+      type: "object",
+      description: "Policy for permitted automatic remediation inside the worktree"
+    },
     domainPackId: {
       type: "string",
       description: "Optional domain pack whose shaping hooks should influence generated questions and tasks"
@@ -471,9 +552,17 @@ var ADD_WORKTREE = {
       type: "array",
       description: "Worktree IDs blocked by this worktree"
     },
-    gate: {
+    staffingHint: {
       type: "string",
-      description: "Exit gate name for this worktree"
+      description: "Suggested staffing or agent allocation note"
+    },
+    lensId: {
+      type: "string",
+      description: "Lens that scopes this worktree when applicable"
+    },
+    lastReconciledAt: {
+      type: "number",
+      description: "Timestamp when worktree metadata was last reconciled"
     }
   },
   required: ["title", "topicId"],
@@ -503,7 +592,7 @@ var MERGE = {
     worktreeId: { type: "string", description: "The worktree to merge" },
     outcomes: {
       type: "array",
-      description: "Scoring outcomes for each belief: { beliefId, confidence, rationale }"
+      description: "Merge outcomes as key-finding strings, or scoring outcomes for beliefs: { beliefId, confidence, rationale }"
     },
     summary: { type: "string", description: "Overall findings summary" }
   },
@@ -3522,6 +3611,69 @@ var GENERATE_SESSION_HANDOFF = {
   tier: "showcase",
   internal: true
 };
+var BEGIN_BUILD_SESSION = {
+  name: "begin_build_session",
+  description: "Bootstrap a coding build session for a Lucern worktree. Like `git worktree add` plus `git status` \u2014 returns the compact context packet an agent needs before editing.",
+  parameters: {
+    worktreeId: {
+      type: "string",
+      description: "The Lucern worktree ID to bootstrap."
+    },
+    branch: {
+      type: "string",
+      description: "Optional git branch name. Auto-generated from the worktree name when omitted."
+    },
+    branchBase: {
+      type: "string",
+      description: 'Base branch for the feature branch. Default: "staging".'
+    },
+    prBase: {
+      type: "string",
+      description: 'Target branch for the PR. Default: "staging".'
+    },
+    sessionMode: {
+      type: "string",
+      description: 'Session mode: "async" for Codex/headless or "interactive" for live sessions.',
+      enum: ["async", "interactive"]
+    },
+    activateIfPlanning: {
+      type: "boolean",
+      description: "When true, automatically activate a planning worktree during bootstrap."
+    }
+  },
+  required: ["worktreeId"],
+  response: {
+    description: "A compact build-session packet with worktree metadata, graph anchors, questions, dependencies, and git defaults.",
+    fields: {
+      topicId: "string \u2014 canonical topic scope",
+      topicName: "string \u2014 human-readable topic name",
+      worktreeId: "string \u2014 worktree ID",
+      worktreeName: "string \u2014 human-readable worktree name",
+      branch: "string \u2014 git branch name",
+      branchBase: "string \u2014 base branch",
+      prBase: "string \u2014 PR target branch",
+      campaign: "number | null \u2014 top-level pipeline campaign",
+      lane: "string \u2014 campaign lane",
+      gate: "string \u2014 exit gate",
+      hypothesis: "string \u2014 worktree hypothesis",
+      focus: "string \u2014 session focus",
+      status: "string \u2014 worktree status after optional activation",
+      sessionMode: "string \u2014 async | interactive",
+      targetBeliefIds: "array \u2014 scoped belief IDs",
+      targetQuestionIds: "array \u2014 scoped question IDs",
+      topBeliefs: "array \u2014 highest-confidence scoped beliefs",
+      openQuestions: "array \u2014 open scoped questions",
+      resolvedDecisions: "array \u2014 answered questions summarized for the session",
+      dependencies: "array \u2014 upstream worktrees",
+      unblocks: "array \u2014 downstream worktrees",
+      mergeOrderNotes: "string \u2014 merge ordering advisory"
+    }
+  },
+  ownerModule: "bootstrap",
+  ontologyPrimitive: "worktree",
+  tier: "showcase",
+  internal: true
+};
 var MCP_TOOL_CONTRACTS = {
   // Belief lifecycle (commit, amend, fork, archive)
   create_belief: CREATE_BELIEF,
@@ -3615,6 +3767,7 @@ var MCP_TOOL_CONTRACTS = {
   get_agent_inbox: GET_AGENT_INBOX,
   claim_files: CLAIM_FILES,
   generate_session_handoff: GENERATE_SESSION_HANDOFF,
+  begin_build_session: BEGIN_BUILD_SESSION,
   // Policy / ACL (workhorse)
   check_permission: CHECK_PERMISSION,
   filter_by_permission: FILTER_BY_PERMISSION,
@@ -3828,6 +3981,7 @@ var PLATFORM_INTERNAL_OPERATION_NAMES = [
   "get_change_history",
   "get_failure_log",
   "record_attempt",
+  "begin_build_session",
   "push",
   "open_pull_request",
   "record_judgment",
@@ -3882,7 +4036,6 @@ var SDK_ONLY_OPERATION_NAMES = [
   "find_semantic_orphans"
 ];
 var MCP_ONLY_INTERNAL_OPERATION_NAMES = [
-  "begin_build_session",
   "evaluate_engineering_contract",
   "evaluate_research_contract"
 ];
@@ -4237,8 +4390,55 @@ function surfaceContract(args) {
     }
   });
 }
-
-// src/function-registry/graph.ts
+var traversalLayerSchema = z.enum([
+  "L4",
+  "L3",
+  "L2",
+  "L1",
+  "ontological",
+  "organizational"
+]);
+var traversalModeSchema = z.enum(["low", "medium", "high", "extra_high"]);
+var lineageAliasArgs = z.object({
+  nodeId: z.string().optional().describe("Starting node to traverse from."),
+  startNode: z.string().optional().describe("Starting node alias for traversal callers."),
+  entityId: z.string().optional().describe("Entity identifier alias for impact tracing."),
+  depth: z.number().optional().describe("Traversal depth alias."),
+  maxDepth: z.number().optional().describe("Maximum traversal depth."),
+  mode: traversalModeSchema.optional().describe("Traversal mode."),
+  minLayer: traversalLayerSchema.optional().describe("Minimum epistemic layer to include."),
+  maxLayer: traversalLayerSchema.optional().describe("Maximum epistemic layer to include.")
+});
+var lineageArgs = lineageAliasArgs.extend({
+  nodeId: z.string().describe("Starting node to traverse from.")
+});
+var traverseGraphArgs = lineageAliasArgs.extend({
+  startNode: z.string().describe("Node to start traversal from."),
+  direction: z.enum(["up", "down", "both"]).optional().describe("Traversal direction.")
+});
+var graphNeighborhoodArgs = z.object({
+  globalId: z.string().optional().describe("Single root global ID."),
+  globalIds: z.array(z.string()).optional().describe("Root global IDs for the neighborhood."),
+  maxDepth: z.number().optional().describe("Maximum traversal depth."),
+  topicId: z.string().optional().describe("Topic scope for edge lookup."),
+  limit: z.number().optional().describe("Maximum edges to return.")
+});
+var flagContradictionArgs = z.object({
+  beliefA: z.string().describe("First belief in tension."),
+  beliefB: z.string().describe("Second belief in tension."),
+  topicId: z.string().optional().describe("Topic scope for the contradiction."),
+  description: z.string().optional().describe("Human-readable contradiction."),
+  severity: z.enum(["critical", "high", "medium", "low"]).optional().describe("Contradiction severity."),
+  defeatType: z.string().optional().describe("Defeat type annotation."),
+  supportingInsightIds: z.array(z.string()).optional().describe("Evidence supporting the primary belief."),
+  contradictingInsightIds: z.array(z.string()).optional().describe("Evidence or beliefs contradicting the primary belief.")
+});
+var discoverEntityConnectionsArgs = lineageAliasArgs.extend({
+  nodeId: z.string().describe("Epistemic node ID to find entity connections for."),
+  topicId: z.string().optional().describe("Topic scope override."),
+  minScore: z.number().optional().describe("Minimum match score."),
+  limit: z.number().optional().describe("Maximum candidates to return.")
+});
 var contradictionSeverity = (value) => {
   switch (value) {
     case "critical":
@@ -4293,7 +4493,8 @@ var graphContracts = [
       functionName: "getLineage",
       kind: "query",
       inputProjection: lineageInput
-    }
+    },
+    args: traverseGraphArgs
   }),
   surfaceContract({
     name: "get_graph_neighborhood",
@@ -4309,7 +4510,8 @@ var graphContracts = [
       functionName: "getByTopic",
       kind: "query",
       inputProjection: topicEdgesInput
-    }
+    },
+    args: graphNeighborhoodArgs
   }),
   surfaceContract({
     name: "get_graph_structure_analysis",
@@ -4358,7 +4560,8 @@ var graphContracts = [
       functionName: "create",
       kind: "mutation",
       inputProjection: flagContradictionInput
-    }
+    },
+    args: flagContradictionArgs
   }),
   surfaceContract({
     name: "detect_confirmation_bias",
@@ -4449,7 +4652,8 @@ var graphContracts = [
       functionName: "getLineage",
       kind: "query",
       inputProjection: lineageInput
-    }
+    },
+    args: discoverEntityConnectionsArgs
   }),
   surfaceContract({
     name: "trigger_belief_review",
@@ -4480,7 +4684,8 @@ var graphContracts = [
       functionName: "getLineage",
       kind: "query",
       inputProjection: lineageInput
-    }
+    },
+    args: lineageArgs
   })
 ];