@lucern/contracts 0.3.0-alpha.9 → 1.0.0

package/dist/sdk-tools.contract.js

@@ -1,3 +1,17 @@
+// src/types/reasoning-method.ts
+var REASONING_METHODS = [
+  "deductive",
+  "inductive",
+  "abductive",
+  "analogical",
+  "causal",
+  "correlational",
+  "testimonial",
+  "statistical",
+  "implicit",
+  "pattern_match"
+];
+
 // src/lens-workflow.contract.ts
 var LENS_PERSPECTIVE_TYPES = [
   "investigation",
@@ -829,19 +843,23 @@ var FIND_CONTRADICTIONS = {
 };
 var CREATE_EDGE = {
   name: "create_edge",
-  description: "Commit a typed relationship between two nodes in the reasoning graph. Like `git commit` \u2014 an atomic write that declares a dependency between nodes. The engine enforces layer transition rules \u2014 for example, L1 \u2192 L3 direct edges are forbidden (must go through L2).",
+  description: "Commit a typed relationship between two nodes in the reasoning graph. Like `git commit` \u2014 an atomic write that declares a dependency between nodes. Accepts any public epistemic edge type between public graph node refs so agents can author the full spine.",
   parameters: {
-    sourceId: {
-      type: "string",
-      description: "Source node of the relationship"
+    from: {
+      type: "object",
+      description: "Source graph ref, e.g. { kind: 'epistemic_node', nodeId: '...', nodeType: 'topic' }"
     },
-    targetId: {
-      type: "string",
-      description: "Target node of the relationship"
+    to: {
+      type: "object",
+      description: "Target graph ref, e.g. { kind: 'epistemic_node', nodeId: '...', nodeType: 'belief' }"
     },
     edgeType: {
       type: "string",
-      description: "Relationship type (informs, tests, depends_on, supersedes, etc.)"
+      description: "Relationship type from the public epistemic edge enum."
+    },
+    globalId: {
+      type: "string",
+      description: "Optional idempotent edge global ID."
     },
     weight: {
       type: "number",
@@ -851,10 +869,14 @@ var CREATE_EDGE = {
     reasoningMethod: {
       type: "string",
       description: "How this was determined",
-      enum: ["deductive", "inductive", "abductive", "analogical", "empirical"]
+      enum: [...REASONING_METHODS]
+    },
+    metadata: {
+      type: "object",
+      description: "Optional edge metadata."
     }
   },
-  required: ["sourceId", "targetId", "edgeType"],
+  required: ["from", "to", "edgeType"],
   response: {
     description: "The created edge",
     fields: {
@@ -868,6 +890,240 @@ var CREATE_EDGE = {
   ontologyPrimitive: "edge",
   tier: "showcase"
 };
+var UPDATE_EDGE = {
+  name: "update_edge",
+  description: "Amend metadata on an existing graph edge. Like `git commit --amend` \u2014 changes the edge annotation without recreating the relationship.",
+  parameters: {
+    edgeId: { type: "string", description: "Edge ID or global ID to update" },
+    weight: { type: "number", description: "Updated edge weight" },
+    confidence: { type: "number", description: "Updated confidence" },
+    context: { type: "string", description: "Updated human-readable context" },
+    derivationType: { type: "string", description: "Updated derivation type" },
+    metadata: { type: "object", description: "Updated metadata" }
+  },
+  required: ["edgeId"],
+  response: {
+    description: "Edge update result",
+    fields: { success: "boolean" }
+  },
+  ownerModule: "graph-primitives",
+  ontologyPrimitive: "edge",
+  tier: "workhorse"
+};
+var REMOVE_EDGE = {
+  name: "remove_edge",
+  description: "Remove one graph edge by ID. Like `git rm` \u2014 deletes a single explicit relationship from the spine.",
+  parameters: {
+    edgeId: { type: "string", description: "Edge ID or global ID to remove" }
+  },
+  required: ["edgeId"],
+  response: {
+    description: "Edge removal result",
+    fields: { success: "boolean" }
+  },
+  ownerModule: "graph-primitives",
+  ontologyPrimitive: "edge",
+  tier: "workhorse"
+};
+var REMOVE_EDGES_BETWEEN = {
+  name: "remove_edges_between",
+  description: "Remove graph edges between two nodes. Like `git rm <pathspec>` \u2014 deletes relationships matching a source, target, and optional type.",
+  parameters: {
+    fromNodeId: { type: "string", description: "Source node ID or global ID" },
+    toNodeId: { type: "string", description: "Target node ID or global ID" },
+    edgeType: { type: "string", description: "Optional edge type filter" }
+  },
+  required: ["fromNodeId", "toNodeId"],
+  response: {
+    description: "Matched edge removal result",
+    fields: { deleted: "number" }
+  },
+  ownerModule: "graph-primitives",
+  ontologyPrimitive: "edge",
+  tier: "workhorse"
+};
+var BATCH_CREATE_EDGES = {
+  name: "batch_create_edges",
+  description: "Commit multiple typed graph edges. Like `git commit` with many staged paths \u2014 writes a batch of explicit relationships atomically per edge.",
+  parameters: {
+    edges: {
+      type: "array",
+      description: "Edges to create, each with from, to, edgeType, and optional weight/confidence/context."
+    },
+    skipLayerValidation: {
+      type: "boolean",
+      description: "Skip kernel layer validation for trusted materialization flows."
+    }
+  },
+  required: ["edges"],
+  response: {
+    description: "Batch edge creation result",
+    fields: {
+      created: "number",
+      results: "array",
+      errors: "array"
+    }
+  },
+  ownerModule: "graph-primitives",
+  ontologyPrimitive: "edge",
+  tier: "workhorse"
+};
+var CREATE_EPISTEMIC_NODE = {
+  name: "create_epistemic_node",
+  description: "Commit a generic epistemic graph node. Like `git commit` \u2014 creates a canonical node in the public spine for topics, beliefs, evidence, questions, answers, sources, and entities.",
+  parameters: {
+    globalId: { type: "string", description: "Optional idempotent node global ID" },
+    nodeType: { type: "string", description: "Public epistemic node type" },
+    canonicalText: { type: "string", description: "Canonical node text" },
+    text: { type: "string", description: "Alias for canonicalText" },
+    contentHash: { type: "string", description: "Optional idempotency content hash" },
+    sourceType: { type: "string", description: "Source type for provenance" },
+    topicId: { type: "string", description: "Optional topic scope" },
+    content: { type: "string", description: "Extended content" },
+    title: { type: "string", description: "Display title" },
+    metadata: { type: "object", description: "Optional node metadata" }
+  },
+  required: ["nodeType"],
+  response: {
+    description: "Created node result",
+    fields: {
+      nodeId: "string",
+      nodeGlobalId: "string",
+      isDuplicate: "boolean"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var GET_EPISTEMIC_NODE = {
+  name: "get_epistemic_node",
+  description: "Read one epistemic graph node. Like `git show` \u2014 resolves a canonical spine node by ID or global ID.",
+  parameters: {
+    nodeId: { type: "string", description: "Node ID or global ID" }
+  },
+  required: ["nodeId"],
+  response: {
+    description: "The resolved node",
+    fields: { node: "object" }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var LIST_EPISTEMIC_NODES = {
+  name: "list_epistemic_nodes",
+  description: "List epistemic graph nodes. Like `git ls-tree` \u2014 lists canonical spine nodes by topic, type, status, or search query.",
+  parameters: {
+    topicId: { type: "string", description: "Optional topic scope" },
+    nodeType: { type: "string", description: "Optional node type filter" },
+    status: { type: "string", description: "Optional lifecycle status" },
+    searchQuery: { type: "string", description: "Optional text search query" },
+    limit: { type: "number", description: "Maximum nodes to return" }
+  },
+  required: [],
+  response: {
+    description: "Matching nodes",
+    fields: { nodes: "array" }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var UPDATE_EPISTEMIC_NODE = {
+  name: "update_epistemic_node",
+  description: "Amend an epistemic graph node. Like `git commit --amend` \u2014 updates mutable node metadata, text, status, or verification fields.",
+  parameters: {
+    nodeId: { type: "string", description: "Node ID or global ID" },
+    canonicalText: { type: "string", description: "Updated canonical text" },
+    text: { type: "string", description: "Alias for canonicalText" },
+    contentHash: { type: "string", description: "Updated content hash" },
+    content: { type: "string", description: "Updated content" },
+    title: { type: "string", description: "Updated display title" },
+    metadata: { type: "object", description: "Updated metadata" },
+    confidence: { type: "number", description: "Updated confidence" },
+    verificationStatus: { type: "string", description: "Updated verification status" },
+    status: { type: "string", description: "Updated lifecycle status" }
+  },
+  required: ["nodeId"],
+  response: {
+    description: "Node update result",
+    fields: { success: "boolean" }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var ARCHIVE_EPISTEMIC_NODE = {
+  name: "archive_epistemic_node",
+  description: "Archive an epistemic graph node. Like `git rm --cached` \u2014 removes a node from active traversal without hard-deleting it.",
+  parameters: {
+    nodeId: { type: "string", description: "Node ID or global ID" }
+  },
+  required: ["nodeId"],
+  response: {
+    description: "Archive result",
+    fields: { success: "boolean", effectiveStatus: "string" }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var VERIFY_EPISTEMIC_NODE = {
+  name: "verify_epistemic_node",
+  description: "Record verification state on an epistemic graph node. Like `git tag` \u2014 marks the node with a reviewed verification state.",
+  parameters: {
+    nodeId: { type: "string", description: "Node ID or global ID" },
+    verificationStatus: { type: "string", description: "Verification status" },
+    confidence: { type: "number", description: "Optional confidence update" }
+  },
+  required: ["nodeId", "verificationStatus"],
+  response: {
+    description: "Verification result",
+    fields: { success: "boolean" }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var SUPERSEDE_EPISTEMIC_NODE = {
+  name: "supersede_epistemic_node",
+  description: "Supersede an epistemic graph node with a new version. Like `git commit --amend` on an immutable history branch \u2014 creates the replacement and marks the old node superseded.",
+  parameters: {
+    oldNodeId: { type: "string", description: "Node ID or global ID to supersede" },
+    newGlobalId: { type: "string", description: "Optional replacement global ID" },
+    newCanonicalText: { type: "string", description: "Replacement canonical text" },
+    text: { type: "string", description: "Alias for newCanonicalText" },
+    newContentHash: { type: "string", description: "Optional replacement content hash" },
+    reason: { type: "string", description: "Reason for superseding" }
+  },
+  required: ["oldNodeId"],
+  response: {
+    description: "Supersede result",
+    fields: { oldNodeId: "string", newNodeId: "string" }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var BATCH_CREATE_EPISTEMIC_NODES = {
+  name: "batch_create_epistemic_nodes",
+  description: "Commit multiple epistemic graph nodes. Like `git commit` with many staged files \u2014 writes a batch of canonical spine nodes.",
+  parameters: {
+    nodes: {
+      type: "array",
+      description: "Nodes to create with nodeType, canonicalText/text, and optional metadata."
+    }
+  },
+  required: ["nodes"],
+  response: {
+    description: "Batch node creation result",
+    fields: { created: "number", results: "array" }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
 var RECORD_JUDGMENT = {
   name: "record_judgment",
   description: "Record a judgment \u2014 an irreversible commitment based on the current epistemic state. Like a `git tag` marking a release. A judgment synthesizes beliefs, evidence, and uncertainties into a determination. Once issued, a judgment is evaluated against the epistemic state that existed when it was made (knowledge horizon evaluation, Invariant #10).",
@@ -2067,8 +2323,8 @@ var IDENTITY_WHOAMI = {
   response: {
     description: "Canonical identity summary for the current session",
     fields: {
-      principalId: "string \u2014 canonical federated principal identifier",
-      principalType: "string \u2014 human, service, or agent",
+      principalId: "string \u2014 canonical principal identifier; for humans this is the Clerk user_... ID",
+      principalType: "string \u2014 human, service, agent, group, or external_viewer",
       tenantId: "string | undefined \u2014 resolved tenant scope",
       workspaceId: "string | undefined \u2014 resolved workspace scope",
       scopes: "string[] | undefined \u2014 granted scopes for this session",
@@ -2079,6 +2335,49 @@ var IDENTITY_WHOAMI = {
   ontologyPrimitive: "identity",
   tier: "workhorse"
 };
+var RESOLVE_INTERACTIVE_PRINCIPAL = {
+  name: "resolve_interactive_principal",
+  description: "Read the Permit-backed Lucern principal context for an authenticated Clerk user. Like `git config --get user.email` plus the repository ACL \u2014 resolves the Clerk subject into tenant/workspace authorization context.",
+  parameters: {
+    clerkId: {
+      type: "string",
+      description: "Authenticated Clerk subject (`sub`). Clerk proves identity only; it is not the authorization record."
+    },
+    tenantId: {
+      type: "string",
+      description: "Optional tenant scope. Omit only when the Clerk alias is globally unambiguous."
+    },
+    workspaceId: {
+      type: "string",
+      description: "Optional workspace scope. Required when the principal has access to multiple workspaces and no default can be inferred."
+    },
+    providerProjectId: {
+      type: "string",
+      description: "Optional Clerk project or provider instance id for tenants with multiple identity providers."
+    }
+  },
+  required: ["clerkId"],
+  response: {
+    description: "Permit-backed Lucern principal context for tenant SDK bootstrap",
+    fields: {
+      principalId: "string \u2014 canonical Clerk user_... ID for human sessions",
+      principalType: "string \u2014 human, service, agent, group, or external_viewer",
+      clerkId: "string \u2014 authenticated Clerk subject alias",
+      tenantId: "string \u2014 resolved tenant scope",
+      workspaceId: "string | null \u2014 resolved workspace scope",
+      roles: "string[] \u2014 effective Permit roles",
+      scopes: "string[] \u2014 effective scopes derived from Permit/control-plane projection",
+      groupIds: "string[] \u2014 active Permit group memberships",
+      principalStatus: "string \u2014 active, invited, suspended, disabled, revoked, or missing",
+      tenantStatus: "string \u2014 projected tenant resource status",
+      workspaceStatus: "string \u2014 projected workspace resource status",
+      permit: "object \u2014 Permit subject, tenant, and optional workspace tuple"
+    }
+  },
+  ownerModule: "control-plane",
+  ontologyPrimitive: "identity",
+  tier: "workhorse"
+};
 var COMPILE_CONTEXT = {
   name: "compile_context",
   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.",
@@ -2340,6 +2639,10 @@ var CREATE_TASK = {
     tags: {
       type: "array",
       description: "Free-form string tags"
+    },
+    metadata: {
+      type: "object",
+      description: "Structured task metadata for handoff context and routing hints"
     }
   },
   required: ["title"],
@@ -2413,6 +2716,10 @@ var UPDATE_TASK = {
       type: "string",
       description: "Updated status",
       enum: ["todo", "in_progress", "blocked", "done"]
+    },
+    metadata: {
+      type: "object",
+      description: "Structured task metadata to replace or refine"
     }
   },
   required: ["taskId"],
@@ -2460,6 +2767,10 @@ var CREATE_TOPIC = {
   name: "create_topic",
   description: "Create a new topic container for scoping knowledge. Like `git init` \u2014 initializes a new repository for a knowledge domain. Topics are hierarchical: a deal topic can nest under a theme topic. Types: domain, theme, deal, strategy, constitution, project, portfolio.",
   parameters: {
+    globalId: {
+      type: "string",
+      description: "Optional idempotent topic global ID"
+    },
     name: { type: "string", description: "Topic name" },
     type: {
       type: "string",
@@ -2470,6 +2781,18 @@ var CREATE_TOPIC = {
       type: "string",
       description: "Optional parent topic for nesting"
     },
+    parentTopicGlobalId: {
+      type: "string",
+      description: "Optional parent topic global ID for nesting"
+    },
+    tenantId: { type: "string", description: "Optional tenant scope" },
+    workspaceId: { type: "string", description: "Optional workspace scope" },
+    visibility: {
+      type: "string",
+      description: "Topic visibility",
+      enum: ["private", "team", "firm", "external", "public"]
+    },
+    metadata: { type: "object", description: "Optional topic metadata" },
     createdBy: { type: "string", description: "Who created this topic" }
   },
   required: ["name", "type"],
@@ -2478,6 +2801,9 @@ var CREATE_TOPIC = {
     fields: {
       id: "string \u2014 topic ID",
       globalId: "string \u2014 globally unique ID",
+      topicGlobalId: "string \u2014 topic global ID",
+      epistemicNodeId: "string \u2014 materialized topic node ID",
+      epistemicNodeGlobalId: "string \u2014 materialized topic node global ID",
       depth: "number \u2014 nesting depth"
     }
   },
@@ -2608,6 +2934,65 @@ var GET_TOPIC_TREE = {
   ontologyPrimitive: "graph",
   tier: "workhorse"
 };
+var MATERIALIZE_TOPIC_GRAPH = {
+  name: "materialize_topic_graph",
+  description: "Backfill the topic graph spine. Like `git fsck --connectivity-only` with repair enabled \u2014 creates missing topic nodes and parent-child edges idempotently.",
+  parameters: {
+    rootTopicId: {
+      type: "string",
+      description: "Optional root topic for a bounded materialization pass"
+    },
+    dryRun: {
+      type: "boolean",
+      description: "When true, report missing rows without writing them"
+    }
+  },
+  required: [],
+  response: {
+    description: "Topic graph materialization counts",
+    fields: {
+      topicsSeen: "number",
+      nodesCreated: "number",
+      nodesExisting: "number",
+      edgesCreated: "number",
+      edgesExisting: "number",
+      errors: "array"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
+var GET_TOPIC_GRAPH_SPINE = {
+  name: "get_topic_graph_spine",
+  description: "Verify the topic graph spine. Like `git fsck` \u2014 reads topics, materialized topic nodes, parent-child edges, and missing spine rows.",
+  parameters: {
+    rootTopicId: {
+      type: "string",
+      description: "Optional root topic for a bounded verifier pass"
+    },
+    includeTopicBeliefEdges: {
+      type: "boolean",
+      description: "Include topic -> belief edges in the verifier payload"
+    }
+  },
+  required: [],
+  response: {
+    description: "Topic graph spine verification payload",
+    fields: {
+      ok: "boolean",
+      counts: "object",
+      topics: "array",
+      topicNodes: "array",
+      parentEdges: "array",
+      missingTopicNodes: "array",
+      missingParentEdges: "array"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse"
+};
 var GET_CODE_CONTEXT = {
   name: "get_code_context",
   description: "Returns code-grounded beliefs, contracts, migration states, and failed attempts anchored to a specific file or function path. Like `git log -- <path>` \u2014 filters the knowledge graph to nodes anchored to a file path via metadata.codeAnchors. Results are separated by coding belief type: decisions, contracts, migrations, patterns, deprecations, and failures.",
@@ -2803,7 +3188,7 @@ var MANAGE_WRITE_POLICY = {
     },
     role: {
       type: "string",
-      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal', 'user:analyst'."
+      description: "Role to set policy for (required for 'set'). E.g. 'agent:internal' or a Permit role key such as 'workspace_admin'."
     },
     permission: {
       type: "string",
@@ -3790,6 +4175,9 @@ var BEGIN_BUILD_SESSION = {
       sessionMode: "string \u2014 async | interactive",
       targetBeliefIds: "array \u2014 scoped belief IDs",
       targetQuestionIds: "array \u2014 scoped question IDs",
+      taskIds: "array \u2014 assigned task IDs for this worktree",
+      incompleteTaskIds: "array \u2014 assigned task IDs that still require done/deferred/blocked proof",
+      tasks: "array \u2014 assigned task packet with id, title, status, priority, links, and summaries",
       topBeliefs: "array \u2014 highest-confidence scoped beliefs",
       openQuestions: "array \u2014 open scoped questions",
       resolvedDecisions: "array \u2014 answered questions summarized for the session",
@@ -3845,6 +4233,19 @@ var MCP_TOOL_CONTRACTS = {
   bisect_confidence: BISECT_CONFIDENCE,
   // Edges (commit)
   create_edge: CREATE_EDGE,
+  update_edge: UPDATE_EDGE,
+  remove_edge: REMOVE_EDGE,
+  remove_edges_between: REMOVE_EDGES_BETWEEN,
+  batch_create_edges: BATCH_CREATE_EDGES,
+  // Epistemic node spine (commit/amend/show)
+  create_epistemic_node: CREATE_EPISTEMIC_NODE,
+  get_epistemic_node: GET_EPISTEMIC_NODE,
+  list_epistemic_nodes: LIST_EPISTEMIC_NODES,
+  update_epistemic_node: UPDATE_EPISTEMIC_NODE,
+  archive_epistemic_node: ARCHIVE_EPISTEMIC_NODE,
+  verify_epistemic_node: VERIFY_EPISTEMIC_NODE,
+  supersede_epistemic_node: SUPERSEDE_EPISTEMIC_NODE,
+  batch_create_epistemic_nodes: BATCH_CREATE_EPISTEMIC_NODES,
   // Judgments (tag)
   record_judgment: RECORD_JUDGMENT,
   // Graph intelligence (showcase)
@@ -3879,6 +4280,7 @@ var MCP_TOOL_CONTRACTS = {
   update_worktree_targets: UPDATE_WORKTREE_TARGETS,
   update_worktree_metadata: UPDATE_WORKTREE_METADATA,
   identity_whoami: IDENTITY_WHOAMI,
+  resolve_interactive_principal: RESOLVE_INTERACTIVE_PRINCIPAL,
   compile_context: COMPILE_CONTEXT,
   record_scope_learning: RECORD_SCOPE_LEARNING,
   pipeline_snapshot: PIPELINE_SNAPSHOT,
@@ -3918,6 +4320,8 @@ var MCP_TOOL_CONTRACTS = {
   get_topic: GET_TOPIC,
   update_topic: UPDATE_TOPIC,
   get_topic_tree: GET_TOPIC_TREE,
+  materialize_topic_graph: MATERIALIZE_TOPIC_GRAPH,
+  get_topic_graph_spine: GET_TOPIC_GRAPH_SPINE,
   // Coding intelligence (code-grounded knowledge)
   get_code_context: GET_CODE_CONTEXT,
   get_change_history: GET_CHANGE_HISTORY,