@lucern/contracts 1.0.0 → 1.0.1

package/dist/tool-contracts.pipeline-coordination.js

@@ -0,0 +1,684 @@
+// src/tool-contracts.pipeline-coordination.ts
+var RECORD_SCOPE_LEARNING = {
+  name: "record_scope_learning",
+  description: "Write a structured learning entry into the epistemic spine. Like `git commit` for scope learnings \u2014 records evidence, can attach to a belief, and can open a follow-up belief/question in one atomic workflow.",
+  parameters: {
+    topicId: { type: "string", description: "Topic scope ID" },
+    summary: { type: "string", description: "Atomic learning statement" },
+    title: {
+      type: "string",
+      description: "Optional evidence title, such as a commit, doc, or issue."
+    },
+    body: {
+      type: "string",
+      description: "Optional rich evidence body. If omitted, body is synthesized from summary and touched paths."
+    },
+    contentType: {
+      type: "string",
+      description: "Optional evidence body format, such as markdown or text."
+    },
+    sourceKind: {
+      type: "string",
+      description: "Source type for the learning event",
+      enum: ["commit", "merge", "doc", "issue", "manual"]
+    },
+    sourceRef: {
+      type: "string",
+      description: "Optional source reference, such as SHA, PR number, or URL slug."
+    },
+    sourceUrl: { type: "string", description: "Optional canonical source URL" },
+    touchedPaths: {
+      type: "array",
+      description: "Optional touched file paths for retrieval hints"
+    },
+    tags: { type: "array", description: "Optional tags" },
+    linkedBeliefNodeId: {
+      type: "string",
+      description: "Optional belief to attach evidence to"
+    },
+    evidenceRelation: {
+      type: "string",
+      description: "Relation to linked belief",
+      enum: ["supports", "contradicts"]
+    },
+    confidence: { type: "number", description: "Optional confidence in [0,1]" },
+    createQuestionText: {
+      type: "string",
+      description: "Optional follow-up question text"
+    },
+    createBeliefText: {
+      type: "string",
+      description: "Optional new belief text"
+    },
+    beliefType: {
+      type: "string",
+      description: "Optional belief type for createBeliefText"
+    }
+  },
+  required: ["summary"],
+  response: {
+    description: "Created learning artifacts",
+    fields: {
+      topicId: "string \u2014 resolved topic ID",
+      evidenceNodeId: "string",
+      linkedBeliefNodeId: "string | null",
+      createdQuestionId: "string | null",
+      createdBeliefId: "string | null",
+      sourceUrl: "string",
+      createdAt: "number"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "evidence",
+  tier: "workhorse",
+  internal: true
+};
+var PIPELINE_SNAPSHOT = {
+  name: "pipeline_snapshot",
+  description: "Summarize a topic's worktree pipeline in campaign-and-lane form. Like `git status --short` for Lucern execution \u2014 returns the hinge worktree, next planned wave, blockers, critical path, superseded work, and graph hygiene debt.",
+  parameters: {
+    topicId: { type: "string", description: "Topic scope ID" }
+  },
+  required: ["topicId"],
+  response: {
+    description: "Human-oriented pipeline summary for a single topic scope",
+    fields: {
+      topicId: "string",
+      topicName: "string",
+      currentCampaign: "number | null",
+      nextCampaign: "number | null",
+      activeWorktrees: "array \u2014 current hinge worktree(s)",
+      nextWave: "array \u2014 worktrees in the next planned campaign",
+      readyNow: "array \u2014 planning worktrees with dependencies completed",
+      blockedBy: "array \u2014 grouped blockers",
+      criticalPath: "array \u2014 ordered incomplete worktree chain",
+      campaigns: "array \u2014 incomplete worktrees grouped by campaign",
+      superseded: "array \u2014 worktrees marked superseded or not for activation",
+      graphHygiene: "object \u2014 untargeted and taskless worktree debt",
+      riskQuestions: "array \u2014 critical/high open questions",
+      narrative: "array \u2014 concise natural-language summary lines"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var DISCOVER = {
+  name: "discover",
+  description: "Navigate the topic tree to find where knowledge lives. Like `git log --all --grep` \u2014 searches across the graph using bottom-up content matching plus top-down structural scoring.",
+  parameters: {
+    query: {
+      type: "string",
+      description: "What to look for across the topic tree"
+    },
+    topK: {
+      type: "number",
+      description: "How many matching topics to return (default: 3, max: 10)"
+    },
+    includeNeighborhood: {
+      type: "boolean",
+      description: "Whether to include beliefs/questions/evidence for matched topics"
+    }
+  },
+  required: ["query"],
+  response: {
+    description: "Ranked topic matches with optional neighborhood content",
+    fields: {
+      query: "string \u2014 original query",
+      matchedTopics: "array \u2014 ranked topics with scores and paths",
+      neighborhoods: "array \u2014 beliefs, questions, evidence for each match",
+      totalTopicsScored: "number",
+      topicTreeSize: "number"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "showcase",
+  deprecated: "Deprecated: use lucern.context.compile() with topicId"
+};
+var ANALYZE_TOPIC_DENSITY = {
+  name: "analyze_topic_density",
+  description: "Analyze topic belief density and identify natural conceptual clusters. Like `git diff --stat` for topic organization \u2014 detects when a topic has accumulated too many beliefs and suggests subtopic decomposition.",
+  parameters: {
+    topicId: { type: "string", description: "Topic ID to analyze" },
+    threshold: {
+      type: "number",
+      description: "Belief count threshold for density warning"
+    },
+    minModularity: {
+      type: "number",
+      description: "Minimum modularity score for suggesting decomposition"
+    }
+  },
+  required: ["topicId"],
+  response: {
+    description: "Density analysis with cluster suggestions",
+    fields: {
+      topicId: "string",
+      topicName: "string",
+      beliefCount: "number",
+      edgeCount: "number",
+      threshold: "number",
+      isDense: "boolean",
+      modularity: "number",
+      clusterCount: "number",
+      clusters: "array \u2014 suggested belief clusters",
+      recommendation: "string"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var APPLY_AUTO_BRANCHING = {
+  name: "apply_auto_branching",
+  description: "Execute topic decomposition by creating subtopics and reassigning beliefs. Like `git subtree split` \u2014 splits a dense topic into focused subtopics while preserving belief identity and edges.",
+  parameters: {
+    topicId: { type: "string", description: "Parent topic ID to decompose" },
+    clusters: {
+      type: "array",
+      description: "Cluster definitions from analyze_topic_density, each with name and beliefIds"
+    },
+    dryRun: {
+      type: "boolean",
+      description: "Preview changes without applying them"
+    }
+  },
+  required: ["topicId", "clusters"],
+  response: {
+    description: "Results of the auto-branching operation",
+    fields: {
+      success: "boolean",
+      parentTopicId: "string",
+      createdSubtopics: "array",
+      totalReassigned: "number",
+      totalSkipped: "number",
+      dryRun: "boolean"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "graph",
+  tier: "showcase"
+};
+var SEED_BELIEF_LATTICE = {
+  name: "seed_belief_lattice",
+  description: "Seed belief lattice coverage for a topic based on its resolved ontology. Like `git init` for ontology coverage \u2014 creates or previews seed beliefs for entity types that need a baseline anchor.",
+  parameters: {
+    topicId: {
+      type: "string",
+      description: "Topic scope ID. Lattice seeding must target a child topic."
+    },
+    dryRun: {
+      type: "boolean",
+      description: "Preview seeds without creating them"
+    }
+  },
+  required: [],
+  response: {
+    description: "Lattice seed results with per-entity-type status",
+    fields: {
+      topicId: "string",
+      ontologyResolved: "boolean",
+      ontologyKey: "string | null",
+      ontologyVersion: "string | null",
+      entityTypeCount: "number",
+      seeds: "array \u2014 per-entity-type seed status",
+      summary: "object \u2014 created/existing/scored/total counts",
+      dryRun: "boolean"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "belief",
+  tier: "workhorse",
+  internal: true
+};
+var GET_LATTICE_COVERAGE = {
+  name: "get_lattice_coverage",
+  description: "Report belief lattice coverage for a topic. Like `git fsck` for ontology coverage \u2014 identifies anchored, hollow, and missing entity-type belief coverage.",
+  parameters: {
+    topicId: {
+      type: "string",
+      description: "Topic scope ID to check lattice coverage for"
+    }
+  },
+  required: [],
+  response: {
+    description: "Per-entity-type coverage with overall score",
+    fields: {
+      topicId: "string",
+      ontologyKey: "string | null",
+      ontologyVersion: "string | null",
+      entityTypes: "array \u2014 per-entity-type coverage rows",
+      summary: "object \u2014 total/anchored/hollow/missing/coverageScore"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "belief",
+  tier: "workhorse",
+  internal: true
+};
+var DISCOVER_ENTITY_CONNECTIONS = {
+  name: "discover_entity_connections",
+  description: "Find existing entities that should be connected to a belief/question/evidence node. Like `git log --diff-filter=M` for missing entity connections \u2014 scans entities in scope and suggests bridge edge types.",
+  parameters: {
+    nodeId: {
+      type: "string",
+      description: "Epistemic node ID to find entity connections for"
+    },
+    topicId: {
+      type: "string",
+      description: "Optional topic scope override"
+    },
+    minScore: {
+      type: "number",
+      description: "Minimum match score threshold"
+    },
+    limit: {
+      type: "number",
+      description: "Maximum candidates to return"
+    }
+  },
+  required: ["nodeId"],
+  response: {
+    description: "Ranked entity connection candidates",
+    fields: {
+      nodeId: "string",
+      candidateCount: "number",
+      candidates: "array \u2014 suggested entity bridge candidates"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "ontology",
+  tier: "workhorse"
+};
+var TRIGGER_BELIEF_REVIEW = {
+  name: "trigger_belief_review",
+  description: "Flag beliefs for review after an entity changes. Like `git bisect` for stale beliefs \u2014 traverses bridge edges from the changed entity and creates review questions for stale connected beliefs.",
+  parameters: {
+    entityNodeId: {
+      type: "string",
+      description: "The entity node that changed"
+    },
+    changeDescription: {
+      type: "string",
+      description: "What changed about the entity"
+    },
+    maxQuestions: {
+      type: "number",
+      description: "Maximum review questions to create"
+    }
+  },
+  required: ["entityNodeId"],
+  response: {
+    description: "Affected beliefs and created review questions",
+    fields: {
+      entityNodeId: "string",
+      entityTitle: "string",
+      entityType: "string",
+      changeDescription: "string",
+      affectedBeliefCount: "number",
+      questionsCreated: "number",
+      reviewedBeliefs: "array",
+      questions: "array"
+    }
+  },
+  ownerModule: "reasoning-kernel",
+  ontologyPrimitive: "ontology",
+  tier: "workhorse"
+};
+var EVALUATE_CONTRACT = {
+  name: "evaluate_contract",
+  description: "Run a contract evaluation and record the append-only result. Like `git test` for a belief binding \u2014 executes the evaluator, logs the result, and applies any allowed confidence modulation.",
+  parameters: {
+    contractId: { type: "string", description: "Which contract to evaluate" },
+    trigger: {
+      type: "string",
+      description: "What caused this evaluation"
+    }
+  },
+  required: ["contractId"],
+  response: {
+    description: "The most recent contract evaluation result",
+    fields: {
+      evaluationId: "string",
+      result: "string",
+      status: "string",
+      confidenceBefore: "number",
+      confidenceAfter: "number",
+      rationale: "string"
+    }
+  },
+  ownerModule: "graph-primitives",
+  ontologyPrimitive: "belief",
+  tier: "workhorse"
+};
+var GET_CONTRACT_STATUS = {
+  name: "get_contract_status",
+  description: "Inspect epistemic contracts and their latest evaluations. Like `git status` for verification bindings \u2014 returns the contract rows plus the freshest recorded evaluation for each one.",
+  parameters: {
+    beliefNodeId: {
+      type: "string",
+      description: "Return all contracts attached to a specific belief"
+    },
+    contractId: {
+      type: "string",
+      description: "Return one specific contract by contractId"
+    },
+    status: {
+      type: "string",
+      description: "Optional status filter applied after lookup",
+      enum: ["active", "satisfied", "violated", "expired", "suspended", "archived"]
+    }
+  },
+  required: [],
+  response: {
+    description: "Matching contract rows with latest evaluation context",
+    fields: {
+      contracts: "array \u2014 matching contracts with latestEvaluation attached",
+      count: "number"
+    }
+  },
+  ownerModule: "graph-primitives",
+  ontologyPrimitive: "belief",
+  tier: "workhorse"
+};
+var REGISTER_SESSION = {
+  name: "register_session",
+  description: "Announce this agent session's presence to other parallel sessions. Like `git init` for coordination \u2014 creates a session record so other agents can discover you.",
+  parameters: {
+    sessionName: { type: "string", description: "Human-readable session label" },
+    agentType: { type: "string", description: "Agent type" },
+    topicId: { type: "string", description: "Current Lucern topic scope ID" },
+    worktreeId: { type: "string", description: "Active Lucern worktree ID" },
+    gitBranch: { type: "string", description: "Current git branch name" }
+  },
+  required: [],
+  response: {
+    description: "Session registration result",
+    fields: {
+      sessionId: "string",
+      status: "string \u2014 active",
+      isNew: "boolean"
+    }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var HEARTBEAT_SESSION = {
+  name: "heartbeat_session",
+  description: "Update this session's heartbeat and optional status fields. Like `git status` \u2014 signals liveness and updates what you are working on.",
+  parameters: {
+    topicId: { type: "string", description: "Updated topic scope" },
+    worktreeId: { type: "string", description: "Updated worktree ID" },
+    gitBranch: { type: "string", description: "Updated git branch" },
+    status: {
+      type: "string",
+      description: "Session status update",
+      enum: ["active", "idle"]
+    }
+  },
+  required: [],
+  response: {
+    description: "Heartbeat result",
+    fields: {
+      success: "boolean",
+      message: "string"
+    }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var END_SESSION = {
+  name: "end_session",
+  description: "Gracefully end this agent session. Like `git stash` \u2014 marks the session as ended so other agents know you are gone.",
+  parameters: {},
+  required: [],
+  response: {
+    description: "Session end result",
+    fields: {
+      success: "boolean",
+      message: "string"
+    }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var LIST_ACTIVE_SESSIONS = {
+  name: "list_active_sessions",
+  description: "See who else is online with active agent sessions, scope, branch, and file claims. Like `git branch --list` for live agents \u2014 shows active and idle sessions before editing.",
+  parameters: {
+    includeIdle: {
+      type: "boolean",
+      description: "Include idle sessions"
+    }
+  },
+  required: [],
+  response: {
+    description: "List of active/idle agent sessions",
+    fields: {
+      sessions: "array \u2014 active session records"
+    }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var SEND_AGENT_MESSAGE = {
+  name: "send_agent_message",
+  description: "Send a directed message to a specific agent session. Like `git notes` \u2014 leaves a coordination note for a specific peer.",
+  parameters: {
+    toSessionId: { type: "string", description: "Target session ID" },
+    content: { type: "string", description: "Message text" },
+    messageType: {
+      type: "string",
+      description: "Message intent",
+      enum: ["note", "question", "answer", "alert", "handoff"]
+    },
+    relatedBeliefId: {
+      type: "string",
+      description: "Optional related belief node ID"
+    },
+    relatedWorktreeId: {
+      type: "string",
+      description: "Optional related worktree ID"
+    }
+  },
+  required: ["toSessionId", "content"],
+  response: {
+    description: "Message delivery result",
+    fields: { messageId: "string" }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var BROADCAST_MESSAGE = {
+  name: "broadcast_message",
+  description: "Send a message to all active agent sessions. Like `git tag` \u2014 marks an important event visible to everyone.",
+  parameters: {
+    content: { type: "string", description: "Broadcast message text" },
+    messageType: {
+      type: "string",
+      description: "Message intent",
+      enum: ["note", "alert", "handoff"]
+    },
+    relatedBeliefId: {
+      type: "string",
+      description: "Optional related belief node ID"
+    },
+    relatedWorktreeId: {
+      type: "string",
+      description: "Optional related worktree ID"
+    }
+  },
+  required: ["content"],
+  response: {
+    description: "Broadcast result",
+    fields: { messageId: "string" }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var GET_AGENT_INBOX = {
+  name: "get_agent_inbox",
+  description: "Check unread messages addressed to this session. Like `git log --incoming` \u2014 shows direct and broadcast messages from other agents.",
+  parameters: {
+    limit: { type: "number", description: "Max messages to return" },
+    markAsRead: {
+      type: "boolean",
+      description: "Mark returned messages as read"
+    }
+  },
+  required: [],
+  response: {
+    description: "Inbox messages",
+    fields: {
+      messages: "array \u2014 unread direct and broadcast messages"
+    }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var CLAIM_FILES = {
+  name: "claim_files",
+  description: "Declare which files this session is actively editing. Like `git add` for coordination \u2014 tells other sessions what you are touching and returns advisory conflicts.",
+  parameters: {
+    files: {
+      type: "array",
+      description: "File paths this session is actively editing"
+    }
+  },
+  required: ["files"],
+  response: {
+    description: "File claim result with conflict detection",
+    fields: {
+      success: "boolean",
+      conflicts: "array \u2014 conflicting file claims"
+    }
+  },
+  ownerModule: "coordination",
+  ontologyPrimitive: "graph",
+  tier: "workhorse",
+  internal: true
+};
+var GENERATE_SESSION_HANDOFF = {
+  name: "generate_session_handoff",
+  description: "Generate a complete, zero-context handoff message for a new coding session. Like `git format-patch` \u2014 produces a self-contained instruction set that bootstraps a fresh Lucern worktree session.",
+  parameters: {
+    worktreeId: {
+      type: "string",
+      description: "The Lucern worktree ID to generate handoff instructions for"
+    },
+    gitWorktreePath: {
+      type: "string",
+      description: "Optional existing git worktree path"
+    },
+    gitBranchName: {
+      type: "string",
+      description: "Optional branch name for the session"
+    },
+    additionalContext: {
+      type: "string",
+      description: "Optional extra context to include in the handoff"
+    }
+  },
+  required: ["worktreeId"],
+  response: {
+    description: "A complete handoff message ready for a new coding session",
+    fields: {
+      handoffMessage: "string",
+      worktreeId: "string",
+      worktreeName: "string",
+      trackBoundary: "object",
+      needsActivation: "boolean",
+      needsGitSetup: "string \u2014 create | fast-forward | ready"
+    }
+  },
+  ownerModule: "bootstrap",
+  ontologyPrimitive: "worktree",
+  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",
+      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",
+      dependencies: "array \u2014 upstream worktrees",
+      unblocks: "array \u2014 downstream worktrees",
+      mergeOrderNotes: "string \u2014 merge ordering advisory"
+    }
+  },
+  ownerModule: "bootstrap",
+  ontologyPrimitive: "worktree",
+  tier: "showcase",
+  internal: true
+};
+
+export { ANALYZE_TOPIC_DENSITY, APPLY_AUTO_BRANCHING, BEGIN_BUILD_SESSION, BROADCAST_MESSAGE, CLAIM_FILES, DISCOVER, DISCOVER_ENTITY_CONNECTIONS, END_SESSION, EVALUATE_CONTRACT, GENERATE_SESSION_HANDOFF, GET_AGENT_INBOX, GET_CONTRACT_STATUS, GET_LATTICE_COVERAGE, HEARTBEAT_SESSION, LIST_ACTIVE_SESSIONS, PIPELINE_SNAPSHOT, RECORD_SCOPE_LEARNING, REGISTER_SESSION, SEED_BELIEF_LATTICE, SEND_AGENT_MESSAGE, TRIGGER_BELIEF_REVIEW };
+//# sourceMappingURL=tool-contracts.pipeline-coordination.js.map
+//# sourceMappingURL=tool-contracts.pipeline-coordination.js.map