@cleocode/contracts 2026.4.100 → 2026.4.102

package/src/branch-lock.ts

@@ -0,0 +1,254 @@
+/**
+ * Branch-lock and owner-override authentication contracts for T1118.
+ *
+ * Defines types, error codes, and interfaces for the four-layer agent
+ * branch-protection system:
+ *
+ * - L1: Git worktree isolation per spawned agent
+ * - L2: cleo-git-shim binary on PATH for harness-agnostic enforcement
+ * - L3: Filesystem hardening via chmod (+ optional chattr on Linux)
+ * - L4: Owner-override HMAC session authentication with TTY + rate-limit gates
+ *
+ * @task T1118
+ * @adr ADR-055
+ */
+
+// ---------------------------------------------------------------------------
+// L1 — Worktree lifecycle types
+// ---------------------------------------------------------------------------
+
+/**
+ * State of an agent worktree created by orchestrate.spawn.
+ *
+ * @task T1118
+ * @task T1120
+ */
+export interface AgentWorktreeState {
+  /** Absolute path to the worktree directory. */
+  path: string;
+  /** Branch name (format: task/<taskId>). */
+  branch: string;
+  /** Task ID that owns this worktree. */
+  taskId: string;
+  /** Base ref the branch was created from (e.g. "main"). */
+  baseRef: string;
+  /** Project hash for env-var injection. */
+  projectHash: string;
+  /** ISO 8601 timestamp when the worktree was created. */
+  createdAt: string;
+  /** Whether git worktree lock was applied to this entry. */
+  locked: boolean;
+}
+
+/**
+ * Result of creating a worktree during spawn.
+ *
+ * @task T1118
+ * @task T1120
+ */
+export interface WorktreeSpawnResult {
+  /** The created worktree state. */
+  worktree: AgentWorktreeState;
+  /** Environment variables to inject into the agent's process. */
+  envVars: Record<string, string>;
+  /** CWD the agent MUST be started in. */
+  cwd: string;
+  /** Preamble text to prepend to the agent's spawn prompt. */
+  preamble: string;
+}
+
+/**
+ * Result from the orchestrate.worktree.complete operation.
+ *
+ * @task T1118
+ * @task T1120
+ */
+export interface WorktreeCompleteResult {
+  /** Task ID that was completed. */
+  taskId: string;
+  /** Whether the cherry-pick succeeded. */
+  cherryPicked: boolean;
+  /** Number of commits cherry-picked. */
+  commitCount: number;
+  /** Whether the worktree was removed. */
+  worktreeRemoved: boolean;
+  /** Whether the task branch was deleted. */
+  branchDeleted: boolean;
+  /** Error message if any step failed (non-fatal — caller decides). */
+  error?: string;
+}
+
+/**
+ * Result from the orchestrate.worktree.cleanup operation.
+ *
+ * @task T1118
+ * @task T1120
+ */
+export interface WorktreeCleanupResult {
+  /** Number of stale worktrees removed. */
+  removed: number;
+  /** Paths that were removed. */
+  removedPaths: string[];
+  /** Paths that failed to remove (with reasons). */
+  errors: Array<{ path: string; reason: string }>;
+}
+
+// ---------------------------------------------------------------------------
+// L2 — Git shim contract types
+// ---------------------------------------------------------------------------
+
+/**
+ * Environment variables read by the cleo-git-shim binary.
+ *
+ * @task T1118
+ * @task T1121
+ */
+export interface GitShimEnv {
+  /** Agent role. When set to worker|lead|subagent, branch-mutating ops are blocked. */
+  CLEO_AGENT_ROLE?: 'orchestrator' | 'worker' | 'lead' | 'subagent';
+  /** When set to "1", bypass the branch-mutation denylist for one command. */
+  CLEO_ALLOW_BRANCH_OPS?: '1';
+  /** Worktree root path — informational for shim error messages. */
+  CLEO_WORKTREE_ROOT?: string;
+  /** Branch protection mode. */
+  CLEO_BRANCH_PROTECTION?: 'strict' | 'permissive' | 'off';
+}
+
+/**
+ * A blocked git subcommand entry in the denylist.
+ *
+ * @task T1118
+ * @task T1121
+ */
+export interface DeniedGitOp {
+  /** The git subcommand (e.g. "checkout"). */
+  subcommand: string;
+  /** Optional flag that triggers the denial (e.g. "--hard" for reset). */
+  flag?: string;
+  /** Human-readable reason shown in the shim's stderr output. */
+  reason: string;
+}
+
+// ---------------------------------------------------------------------------
+// L3 — Filesystem hardening types
+// ---------------------------------------------------------------------------
+
+/**
+ * Platform capability report for filesystem hardening.
+ *
+ * @task T1118
+ * @task T1122
+ */
+export interface FsHardenCapabilities {
+  /** Whether chmod is available (always true on POSIX). */
+  chmod: boolean;
+  /** Whether chattr is available (Linux ext2/3/4/xfs only). */
+  chattr: boolean;
+  /** Whether chflags is available (macOS). */
+  chflags: boolean;
+  /** Detected platform. */
+  platform: 'linux' | 'macos' | 'windows' | 'wsl' | 'unknown';
+}
+
+/**
+ * State of the filesystem hard-lock for the orchestrator's HEAD.
+ *
+ * @task T1118
+ * @task T1122
+ */
+export interface FsHardenState {
+  /** Whether any lock is currently active. */
+  active: boolean;
+  /** Which mechanism was applied (chmod, chattr, or chflags). */
+  mechanism: 'chmod' | 'chattr' | 'chflags' | 'none';
+  /** Absolute path(s) that were locked. */
+  lockedPaths: string[];
+  /** ISO 8601 timestamp when the lock was applied. */
+  appliedAt?: string;
+}
+
+// ---------------------------------------------------------------------------
+// L4 — Owner override authentication types
+// ---------------------------------------------------------------------------
+
+/**
+ * Record appended to force-bypass.jsonl when an override is used.
+ *
+ * Extends the base ForceBypassRecord with L4-specific authentication fields.
+ *
+ * @task T1118
+ * @task T1123
+ */
+export interface OwnerOverrideAuditRecord {
+  /** ISO 8601 timestamp. */
+  timestamp: string;
+  /** Task ID being verified (may be "*" for session-level). */
+  taskId: string;
+  /** Gate being bypassed. */
+  gate: string;
+  /** Write action performed. */
+  action: string;
+  /** Agent ID that performed the bypass. */
+  agent_id: string;
+  /** Session ID. */
+  session_id: string | null;
+  /** Whether the HMAC token was validated (L4a). */
+  token_validated: boolean;
+  /** Whether TTY was present (L4c). */
+  tty_present: boolean;
+  /** Override count within the current session (L4d). */
+  override_count: number;
+  /** Webhook delivery status (L4d). */
+  webhook_delivered?: boolean;
+  /** Reason supplied by the operator. */
+  reason: string;
+  /** Process ID. */
+  pid: number;
+}
+
+/**
+ * Configuration for the owner override system.
+ *
+ * @task T1118
+ * @task T1123
+ */
+export interface OwnerOverrideConfig {
+  /** Maximum number of overrides allowed per session (default: 3). */
+  maxPerSession: number;
+  /** Optional webhook URL to POST on each bypass. */
+  alertWebhook?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Error codes for branch-lock enforcement
+// ---------------------------------------------------------------------------
+
+/**
+ * Error codes emitted by the branch-lock + override-auth system.
+ *
+ * @task T1118
+ */
+export const BRANCH_LOCK_ERROR_CODES = {
+  /** L2: git shim blocked a branch-mutating operation. */
+  E_GIT_OP_BLOCKED: 'E_GIT_OP_BLOCKED',
+  /** L1: spawn attempted without a worktree handle. */
+  E_WORKTREE_REQUIRED: 'E_WORKTREE_REQUIRED',
+  /** L1: worktree path does not exist or is not a valid git worktree. */
+  E_WORKTREE_INVALID: 'E_WORKTREE_INVALID',
+  /** L1: cherry-pick failed during worktree.complete. */
+  E_CHERRY_PICK_FAILED: 'E_CHERRY_PICK_FAILED',
+  /** L3: filesystem harden failed. */
+  E_FS_HARDEN_FAILED: 'E_FS_HARDEN_FAILED',
+  /** L4a: HMAC token invalid or missing. */
+  E_OVERRIDE_TOKEN_INVALID: 'E_OVERRIDE_TOKEN_INVALID',
+  /** L4b: caller has CLEO_AGENT_ROLE=worker|lead|subagent — override forbidden. */
+  E_OVERRIDE_FORBIDDEN_AGENT_ROLE: 'E_OVERRIDE_FORBIDDEN_AGENT_ROLE',
+  /** L4c: override requires TTY but stdin/stderr is not a TTY. */
+  E_OVERRIDE_NEEDS_TTY: 'E_OVERRIDE_NEEDS_TTY',
+  /** L4d: session override limit exceeded. */
+  E_OVERRIDE_RATE_LIMIT: 'E_OVERRIDE_RATE_LIMIT',
+} as const;
+
+/** Union of all branch-lock error code strings. */
+export type BranchLockErrorCode =
+  (typeof BRANCH_LOCK_ERROR_CODES)[keyof typeof BRANCH_LOCK_ERROR_CODES];

package/src/exit-codes.ts

@@ -111,7 +111,7 @@ export enum ExitCode {
   NEXUS_PROJECT_EXISTS = 76,
   NEXUS_QUERY_FAILED = 77,
   NEXUS_GRAPH_ERROR = 78,
-  NEXUS_RESERVED = 79,
+  NEXUS_IMPACT_CRITICAL = 79,
 
   // === LIFECYCLE ENFORCEMENT (80-84) ===
   LIFECYCLE_GATE_FAILED = 80,

package/src/graph.ts

@@ -154,6 +154,8 @@ export interface GraphNode {
   processIds?: string[];
   /** Kind-specific metadata blob (matches nexus_nodes.meta_json). */
   meta?: Record<string, unknown>;
+  /** Whether this node represents an external module (unresolved import). */
+  isExternal?: boolean;
 }
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -132,6 +132,33 @@ 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 {
+  AgentWorktreeState,
+  BranchLockErrorCode,
+  DeniedGitOp,
+  FsHardenCapabilities,
+  FsHardenState,
+  GitShimEnv,
+  OwnerOverrideAuditRecord,
+  OwnerOverrideConfig,
+  WorktreeCleanupResult,
+  WorktreeCompleteResult,
+  WorktreeSpawnResult,
+} from './branch-lock.js';
+// === Branch-Lock + Owner-Auth Types (T1118) ===
+export { BRANCH_LOCK_ERROR_CODES } from './branch-lock.js';
 export type { AdapterCapabilities } from './capabilities.js';
 // === Code Symbol Types (tree-sitter AST) ===
 export type {
@@ -171,6 +198,7 @@ export type {
   LifecycleEnforcementMode,
   LoggingConfig,
   LogLevel,
+  MemoryBridgeMode,
   OutputConfig,
   OutputFormat,
   ProviderConfig,
@@ -339,6 +367,71 @@ 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,
+  GenerateNexusWikiOptions,
+  NexusWikiResult,
+  WikiDbHandle,
+  WikiStateFile,
+  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 +445,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;
+}