@cleocode/contracts 2026.4.99 → 2026.4.101

package/src/index.ts

@@ -132,6 +132,18 @@ export type {
   ContradictionDetail,
   SupersededEntry,
 } from './brain.js';
+// === Brain Unified-Graph Types (canonical — T989 unification) ===
+export type {
+  BrainConnectionStatus,
+  BrainEdge,
+  BrainGraph,
+  BrainNode,
+  BrainNodeKind,
+  BrainProjectContext,
+  BrainQueryOptions,
+  BrainStreamEvent,
+  BrainSubstrate,
+} from './brain-graph.js';
 export type { AdapterCapabilities } from './capabilities.js';
 // === Code Symbol Types (tree-sitter AST) ===
 export type {
@@ -339,6 +351,68 @@ export type {
   MemoryBridgeContent,
   SessionSummary,
 } from './memory.js';
+export type {
+  Contract,
+  ContractCompatibilityMatrix,
+  ContractExtractionResult,
+  ContractMatch,
+  ContractMatchLevel,
+  ContractTaskLink,
+  GrpcContract,
+  HttpContract,
+  TopicContract,
+} from './nexus-contract-ops.js';
+// === Living Brain SDK Types (T1068 — 5-substrate traversal primitives) ===
+// === Extended Code Reasoning Types (T1069 — reasonWhySymbol + reasonImpactOfChange) ===
+export type {
+  BlastRadiusSummary,
+  BrainMemoryRef,
+  BrainRiskNote,
+  CodeAnchorResult,
+  CodeReasonTrace,
+  ConduitThreadRef,
+  DecisionRef,
+  ImpactFullReport,
+  LbTaskRef,
+  NexusContext,
+  NexusEdgeRef,
+  NexusNodeAnchor,
+  PlasticityMeasure,
+  ProposalRef,
+  ReasonTraceStep,
+  RiskTier,
+  SymbolFullContext,
+  SymbolImpactEntry,
+  TaskCodeImpact,
+  TasksForNodeEntry,
+} from './nexus-living-brain-ops.js';
+// === Nexus Query DSL (recursive CTE operations) ===
+export type {
+  NexusCteAlias,
+  NexusCteMarkdownTable,
+  NexusCteParams,
+  NexusCtePlaceholder,
+  NexusCteResult,
+} from './nexus-query-ops.js';
+// === Route Analysis and Contract Registry Types (T1064, T1065) ===
+export type {
+  RouteMapEntry,
+  RouteMapResult,
+  ShapeCheckCaller,
+  ShapeCheckResult,
+  ShapeCheckStatus,
+} from './nexus-route-ops.js';
+export type {
+  GitLogLinkerResult,
+  LinkTaskResult,
+  SymbolReference,
+  TaskReference,
+} from './nexus-tasks-bridge-ops.js';
+export type {
+  CommunityWikiStats,
+  NexusWikiResult,
+  WikiSymbolRow,
+} from './nexus-wiki-ops.js';
 // === Operations Types (API wire format, namespaced to avoid collision with domain types) ===
 export * as ops from './operations/index.js';
 // Commonly used ops types re-exported at top level for convenience
@@ -352,6 +426,41 @@ export type {
   ParamType,
 } from './operations/params.js';
 export { paramsToCittyArgs } from './operations/params.js';
+// Session operation param/result types — re-exported at top level for typed-dispatch consumers
+// (T975 Wave D · ADR-051 migration)
+export type {
+  DecisionRecord,
+  SessionBriefingShowParams,
+  SessionBriefingShowResult,
+  SessionContextDriftParams,
+  SessionContextDriftResult,
+  SessionDecisionLogParams,
+  SessionDecisionLogResult,
+  SessionEndParams,
+  SessionEndResult,
+  SessionFindParams,
+  SessionFindResult,
+  SessionGcParams,
+  SessionGcResult,
+  SessionHandoffShowParams,
+  SessionHandoffShowResult,
+  SessionListParams,
+  SessionListResult,
+  SessionOps,
+  SessionRecordAssumptionParams,
+  SessionRecordAssumptionResult,
+  SessionRecordDecisionParams,
+  SessionRecordDecisionResult,
+  SessionResumeParams,
+  SessionResumeResult,
+  SessionShowParams,
+  SessionShowResult,
+  SessionStartParams,
+  SessionStatusParams,
+  SessionStatusResult,
+  SessionSuspendParams,
+  SessionSuspendResult,
+} from './operations/session.js';
 // === Orchestration Hierarchy ===
 export {
   type AgentHierarchy,

package/src/nexus-contract-ops.ts

@@ -0,0 +1,244 @@
+/**
+ * Contract extraction and matching types for NEXUS cross-project compatibility.
+ *
+ * A contract represents a callable API (HTTP endpoint, gRPC service, pub/sub topic)
+ * that can be extracted from source code and matched with contracts from other projects
+ * to detect compatibility and integration points.
+ *
+ * @task T1065 — Contract Registry
+ */
+
+/**
+ * HTTP contract extracted from route analysis.
+ *
+ * Represents a single HTTP endpoint with its path, method, and request/response schemas.
+ */
+export interface HttpContract {
+  /** Unique contract ID (format: `http:<projectId>::<path>::<method>`) */
+  id: string;
+
+  /** Project ID this contract belongs to */
+  projectId: string;
+
+  /** Contract type — always 'http' */
+  type: 'http';
+
+  /** HTTP method (GET, POST, PUT, DELETE, PATCH, etc.) */
+  method: string;
+
+  /** Route path (e.g., `/api/v1/tasks`) */
+  path: string;
+
+  /** Request body schema as JSON string (or '{}' if no body) */
+  requestSchemaJson: string;
+
+  /** Response body schema as JSON string */
+  responseSchemaJson: string;
+
+  /** Source symbol ID (format: `<filePath>::<functionName>`) */
+  sourceSymbolId: string;
+
+  /** Route node ID from NEXUS graph */
+  routeNodeId?: string;
+
+  /** Confidence of extraction [0..1] */
+  confidence: number;
+
+  /** Human-readable summary */
+  description?: string;
+}
+
+/**
+ * gRPC contract extracted from proto file analysis.
+ *
+ * Represents a single gRPC service method.
+ * Extraction may be minimal/stub on projects without .proto files.
+ */
+export interface GrpcContract {
+  /** Unique contract ID (format: `grpc:<projectId>::<serviceName>::<methodName>`) */
+  id: string;
+
+  /** Project ID this contract belongs to */
+  projectId: string;
+
+  /** Contract type — always 'grpc' */
+  type: 'grpc';
+
+  /** Service name (e.g., `TaskService`) */
+  serviceName: string;
+
+  /** Method name (e.g., `CreateTask`) */
+  methodName: string;
+
+  /** Request message type name */
+  requestMessageType: string;
+
+  /** Response message type name */
+  responseMessageType: string;
+
+  /** Request message schema as JSON string */
+  requestSchemaJson: string;
+
+  /** Response message schema as JSON string */
+  responseSchemaJson: string;
+
+  /** Source proto file path */
+  sourceProtoFile: string;
+
+  /** Confidence of extraction [0..1] */
+  confidence: number;
+
+  /** Human-readable summary */
+  description?: string;
+}
+
+/**
+ * Topic/pub-sub contract extracted from message queue code patterns.
+ *
+ * Represents a single publish or subscribe to a message topic.
+ * Extraction may be minimal/stub on projects without pub/sub patterns.
+ */
+export interface TopicContract {
+  /** Unique contract ID (format: `topic:<projectId>::<topicName>::<direction>`) */
+  id: string;
+
+  /** Project ID this contract belongs to */
+  projectId: string;
+
+  /** Contract type — always 'topic' */
+  type: 'topic';
+
+  /** Topic name (e.g., `task.created`) */
+  topic: string;
+
+  /** Direction: 'publish' or 'subscribe' */
+  direction: 'publish' | 'subscribe';
+
+  /** Message payload schema as JSON string */
+  payloadSchemaJson: string;
+
+  /** Source symbol ID (format: `<filePath>::<functionName>`) */
+  sourceSymbolId: string;
+
+  /** Confidence of extraction [0..1] */
+  confidence: number;
+
+  /** Human-readable summary */
+  description?: string;
+}
+
+/** Union type of all contract kinds */
+export type Contract = HttpContract | GrpcContract | TopicContract;
+
+/**
+ * Matching level for contract compatibility.
+ *
+ * - 'exact': path + method match exactly (HTTP) or full signature match (gRPC)
+ * - 'name': service/method names match but signatures may differ
+ * - 'fuzzy': BM25 similarity above threshold on path/schema content
+ */
+export type ContractMatchLevel = 'exact' | 'name' | 'fuzzy';
+
+/**
+ * Result of matching two contracts.
+ *
+ * Indicates compatibility between a contract in project A and project B.
+ */
+export interface ContractMatch {
+  /** Matched contract from project A */
+  contractA: Contract;
+
+  /** Matched contract from project B */
+  contractB: Contract;
+
+  /** Matching level (exact → name → fuzzy cascade) */
+  level: ContractMatchLevel;
+
+  /** Similarity score [0..1] where 1.0 is identical */
+  score: number;
+
+  /** Human-readable explanation of the match */
+  reason: string;
+
+  /** Compatibility verdict: 'compatible', 'incompatible', 'partial' */
+  compatibility: 'compatible' | 'incompatible' | 'partial';
+
+  /** Specific incompatibilities if any (e.g., schema mismatches) */
+  incompatibilities?: string[];
+}
+
+/**
+ * Contract compatibility matrix between two projects.
+ *
+ * Result of `cleo nexus contracts show --project-a <p> --project-b <p>`.
+ */
+export interface ContractCompatibilityMatrix {
+  /** Project A ID */
+  projectAId: string;
+
+  /** Project B ID */
+  projectBId: string;
+
+  /** All matched contracts */
+  matches: ContractMatch[];
+
+  /** Count of compatible matches */
+  compatibleCount: number;
+
+  /** Count of incompatible matches */
+  incompatibleCount: number;
+
+  /** Count of partial/unresolved matches */
+  partialCount: number;
+
+  /** Overall compatibility percentage */
+  overallCompatibility: number;
+
+  /** Recommendations for integration */
+  recommendations: string[];
+}
+
+/**
+ * Result of extracting contracts from a project.
+ *
+ * Returned by contract extractors.
+ */
+export interface ContractExtractionResult {
+  /** Project ID */
+  projectId: string;
+
+  /** HTTP contracts found */
+  httpContracts: HttpContract[];
+
+  /** gRPC contracts found */
+  grpcContracts: GrpcContract[];
+
+  /** Topic/pub-sub contracts found */
+  topicContracts: TopicContract[];
+
+  /** Total contracts extracted */
+  totalCount: number;
+
+  /** Any extraction warnings or notes */
+  notes: string[];
+}
+
+/**
+ * Result of linking contracts to affected tasks.
+ *
+ * When a contract's source symbol is touched by a task (via task_touches_symbol edge),
+ * we emit a contract_affected_by_task annotation.
+ */
+export interface ContractTaskLink {
+  /** Contract ID */
+  contractId: string;
+
+  /** Task ID that affects this contract */
+  taskId: string;
+
+  /** Type of change (modified, added, removed) */
+  changeType: 'modified' | 'added' | 'removed';
+
+  /** Timestamp of the linkage */
+  linkedAt: string;
+}

package/src/nexus-living-brain-ops.ts

@@ -0,0 +1,345 @@
+/**
+ * Contract types for the Living Brain SDK traversal primitives (T1068).
+ *
+ * The Living Brain is the cross-substrate query surface for the CLEO agent
+ * intelligence layer. It unifies five substrates — NEXUS (code graph),
+ * BRAIN (memory), TASKS, SENTIENT (proposals), and CONDUIT (messages) — into
+ * a single traversal API.
+ *
+ * These are LEAF types — zero runtime dependencies.
+ *
+ * @task T1068
+ * @epic T1042
+ */
+
+// ---------------------------------------------------------------------------
+// Sub-interfaces — each substrate's projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Caller or callee within the nexus code graph.
+ */
+export interface NexusEdgeRef {
+  /** Nexus node ID. */
+  nodeId: string;
+  /** Human-readable display name. */
+  name: string;
+  /** Source file path (relative to project root). */
+  filePath: string | null;
+  /** Node kind ('function', 'class', 'method', etc.). */
+  kind: string;
+  /** Relation type ('calls', 'imports', 'accesses'). */
+  relationType: string;
+}
+
+/**
+ * Nexus context for a symbol: callers, callees, community, process membership.
+ */
+export interface NexusContext {
+  /** Symbol's own nexus node ID. */
+  symbolId: string;
+  /** Display label. */
+  label: string;
+  /** File path. */
+  filePath: string | null;
+  /** Node kind. */
+  kind: string;
+  /** Community ID this symbol belongs to (if any). */
+  communityId: string | null;
+  /** Nodes that call/import this symbol. */
+  callers: NexusEdgeRef[];
+  /** Nodes this symbol calls/imports. */
+  callees: NexusEdgeRef[];
+  /** Process nodes this symbol participates in. */
+  processes: string[];
+}
+
+/**
+ * A brain memory node (observation, decision, pattern, learning) that
+ * references a code symbol via one of the cross-substrate edge types.
+ */
+export interface BrainMemoryRef {
+  /** Brain page node ID (e.g., 'observation:abc123'). */
+  nodeId: string;
+  /** Node type. */
+  nodeType: string;
+  /** Human-readable label for the memory entry. */
+  label: string;
+  /** Quality score of this memory entry (0.0–1.0). */
+  qualityScore: number;
+  /** Edge type used to connect this memory to the symbol. */
+  edgeType: string;
+  /** Edge weight. */
+  weight: number;
+}
+
+/**
+ * A task reference linking a task to a code symbol.
+ */
+export interface LbTaskRef {
+  /** Task ID (e.g., 'T001'). */
+  taskId: string;
+  /** Display label for the task. */
+  label: string;
+  /** Edge weight (confidence). */
+  weight: number;
+  /** Strategy used to detect the link. */
+  matchStrategy: string;
+}
+
+/**
+ * A sentient proposal entry referencing a code symbol.
+ */
+export interface ProposalRef {
+  /** Source system. */
+  source: string;
+  /** Source ID (nexus node ID for nexus proposals). */
+  sourceId: string;
+  /** Structured proposal title. */
+  title: string;
+  /** Proposal rationale. */
+  rationale: string;
+  /** Proposal weight in [0, 1]. */
+  weight: number;
+}
+
+/**
+ * A conduit message thread that mentions a symbol.
+ *
+ * Returns empty array when conduit.db is absent (T1071 schema not yet present).
+ */
+export interface ConduitThreadRef {
+  /** Conduit message node ID (format: 'conduit:<id>'). */
+  nodeId: string;
+  /** Edge weight. */
+  weight: number;
+}
+
+/**
+ * Plasticity measurement for a symbol — aggregate edge weight from nexus_relations.
+ */
+export interface PlasticityMeasure {
+  /** Sum of edge weights across all nexus_relations involving this symbol. */
+  totalWeight: number;
+  /** Number of edges included in the sum. */
+  edgeCount: number;
+}
+
+// ---------------------------------------------------------------------------
+// Primary return shapes
+// ---------------------------------------------------------------------------
+
+/**
+ * Full cross-substrate context for a code symbol.
+ *
+ * Returned by {@link getSymbolFullContext}.
+ */
+export interface SymbolFullContext {
+  /** Symbol identifier (nexus node ID or name). */
+  symbolId: string;
+  /** Nexus code graph context: callers, callees, community, process. */
+  nexus: NexusContext | null;
+  /** Brain memory nodes (observations, decisions, patterns, learnings) linked to this symbol. */
+  brainMemories: BrainMemoryRef[];
+  /** Tasks that touched files containing this symbol. */
+  tasks: LbTaskRef[];
+  /** Sentient proposals whose sourceId matches this symbol. */
+  sentientProposals: ProposalRef[];
+  /** Conduit message threads mentioning this symbol (empty if conduit.db absent). */
+  conduitThreads: ConduitThreadRef[];
+  /** Plasticity weight sum from nexus_relations. */
+  plasticityWeight: PlasticityMeasure;
+}
+
+/**
+ * Code impact analysis for a task.
+ *
+ * Returned by {@link getTaskCodeImpact}.
+ */
+export interface TaskCodeImpact {
+  /** Task ID. */
+  taskId: string;
+  /** Files listed in the task's files_json array. */
+  files: string[];
+  /** Symbols in those files (from NEXUS). */
+  symbols: SymbolImpactEntry[];
+  /** Aggregate blast radius across all symbols. */
+  blastRadius: BlastRadiusSummary;
+  /** Brain observations with modified_by edges to the task's files. */
+  brainObservations: BrainMemoryRef[];
+  /** Brain decisions linked to this task via brain_memory_links. */
+  decisions: DecisionRef[];
+  /** Highest risk tier across all symbols. */
+  riskScore: RiskTier;
+}
+
+/**
+ * Impact entry for a single symbol in a task's footprint.
+ */
+export interface SymbolImpactEntry {
+  /** Nexus node ID. */
+  nexusNodeId: string;
+  /** Display label. */
+  label: string;
+  /** Symbol kind. */
+  kind: string;
+  /** File path. */
+  filePath: string | null;
+  /** Risk tier from analyzeImpact BFS. */
+  riskLevel: RiskTier;
+  /** Total number of affected nodes in BFS. */
+  totalAffected: number;
+  /** Direct callers (d=1) count. */
+  directCallers: number;
+}
+
+/**
+ * Aggregate blast radius across all symbols in a task's footprint.
+ */
+export interface BlastRadiusSummary {
+  /** Total unique affected nodes across all symbols. */
+  totalAffected: number;
+  /** Maximum risk tier observed. */
+  maxRisk: RiskTier;
+  /** Number of symbols analyzed. */
+  symbolsAnalyzed: number;
+}
+
+/**
+ * A brain decision linked to a task.
+ */
+export interface DecisionRef {
+  /** Decision ID. */
+  decisionId: string;
+  /** Decision text. */
+  decision: string;
+  /** Link type. */
+  linkType: string;
+}
+
+/**
+ * Risk tier for a symbol's impact analysis.
+ */
+export type RiskTier = 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+
+// ---------------------------------------------------------------------------
+// T1069 — Extended Code Reasoning types
+// ---------------------------------------------------------------------------
+
+/**
+ * A single step in a code reasoning trace chain.
+ */
+export interface ReasonTraceStep {
+  /** Step type discriminant. */
+  type: 'decision' | 'observation' | 'task' | 'symbol';
+  /** ID of this entry (brain ID, task ID, or nexus node ID). */
+  id: string;
+  /** Human-readable title or label for this entry. */
+  title: string;
+  /** References or related IDs (e.g., learning IDs for a decision step). */
+  refs: string[];
+}
+
+/**
+ * Full causal trace from a code symbol through brain decisions to tasks.
+ *
+ * Returned by {@link reasonWhySymbol}.
+ */
+export interface CodeReasonTrace {
+  /** The nexus symbol ID queried. */
+  symbolId: string;
+  /** Human-readable narrative summarizing the trace. */
+  narrative: string;
+  /** Ordered chain of trace steps from symbol to root context. */
+  chain: ReasonTraceStep[];
+}
+
+/**
+ * A brain risk note associated with a symbol change.
+ */
+export interface BrainRiskNote {
+  /** Brain node ID. */
+  nodeId: string;
+  /** Node type (observation, decision, etc.). */
+  nodeType: string;
+  /** Human-readable label. */
+  label: string;
+  /** Edge type that connects this note to the symbol. */
+  edgeType: string;
+  /** Risk contribution weight. */
+  weight: number;
+}
+
+/**
+ * Full merged impact report for a code symbol.
+ *
+ * Returned by {@link reasonImpactOfChange}.
+ */
+export interface ImpactFullReport {
+  /** The nexus symbol ID analyzed. */
+  symbolId: string;
+  /** Structural blast radius from analyzeImpact BFS. */
+  structural: {
+    directCallers: number;
+    likelyAffected: number;
+    mayNeedTesting: number;
+    totalAffected: number;
+    riskLevel: RiskTier;
+  };
+  /** Open tasks that reference this symbol (from task_touches_symbol edges). */
+  openTasks: Array<{
+    taskId: string;
+    label: string;
+    weight: number;
+  }>;
+  /** Brain observations/decisions flagging risk for this symbol. */
+  brainRiskNotes: BrainRiskNote[];
+  /** Merged risk score (highest of structural, open-task count, brain notes). */
+  mergedRiskScore: RiskTier;
+  /** Human-readable narrative summarizing the combined risk. */
+  narrative: string;
+}
+
+/**
+ * Code anchor result for a brain memory entry.
+ *
+ * Returned by {@link getBrainEntryCodeAnchors}.
+ */
+export interface CodeAnchorResult {
+  /** Brain entry ID that was queried. */
+  entryId: string;
+  /** Nexus nodes linked to this brain entry via code-reference edges. */
+  nexusNodes: NexusNodeAnchor[];
+  /** For each nexus node, which tasks touched it. */
+  tasksForNodes: TasksForNodeEntry[];
+  /** Sum of weights on all edges anchoring this brain entry to code. */
+  plasticitySignal: number;
+}
+
+/**
+ * A nexus node anchored to a brain entry.
+ */
+export interface NexusNodeAnchor {
+  /** Nexus node ID. */
+  nexusNodeId: string;
+  /** Display label. */
+  label: string;
+  /** File path. */
+  filePath: string | null;
+  /** Node kind. */
+  kind: string;
+  /** Edge type connecting this node to the brain entry. */
+  edgeType: string;
+  /** Edge weight. */
+  weight: number;
+}
+
+/**
+ * Tasks that touched a specific nexus node.
+ */
+export interface TasksForNodeEntry {
+  /** Nexus node ID. */
+  nexusNodeId: string;
+  /** Tasks that touched this node. */
+  tasks: LbTaskRef[];
+}