@cleocode/contracts 2026.4.141 → 2026.4.143

package/src/operations/conduit.ts

@@ -1,8 +1,16 @@
 /**
- * Conduit Domain Operations (5 operations)
+ * Conduit Domain Operations (8 operations: 3 query, 5 mutate)
  *
- * Query operations: 2
- * Mutate operations: 3
+ * Query operations: 3
+ *   - conduit.status   — connection status + unread count
+ *   - conduit.peek     — one-shot poll for messages
+ *   - conduit.listen   — one-shot poll for topic messages (A2A, T1252)
+ * Mutate operations: 5
+ *   - conduit.start    — start continuous polling
+ *   - conduit.stop     — stop polling
+ *   - conduit.send     — send a message
+ *   - conduit.subscribe — subscribe agent to a topic (A2A, T1252)
+ *   - conduit.publish  — publish message to a topic (A2A, T1252)
  *
  * CONDUIT is the agent-to-agent messaging subsystem. The protocol wraps a
  * pluggable Transport (HTTP to cloud SignalDock, LocalTransport over
@@ -16,12 +24,14 @@
  *
  * Registry note (T964 — supersedes ADR-042 Decision 1): the dispatcher
  * registers these operations under `domain: 'conduit'` with short operation
- * names (`status`, `peek`, `start`, `stop`, `send`). The public/HTTP identifier
- * `conduit.<op>` remains the stable wire-format surface and what these
- * contracts describe; CLI and HTTP adapters map between the two forms.
+ * names (`status`, `peek`, `start`, `stop`, `send`, `subscribe`, `publish`,
+ * `listen`). The public/HTTP identifier `conduit.<op>` remains the stable
+ * wire-format surface and what these contracts describe; CLI and HTTP adapters
+ * map between the two forms.
  *
  * @task T910 — Orchestration Coherence v4 (contract surface completion)
  * @task T964 — CONDUIT promotion to canonical domain #15
+ * @task T1422 — Typed-dispatch migration (Wave D, T975 follow-on)
  * @see packages/cleo/src/dispatch/domains/conduit.ts
  * @see packages/contracts/src/conduit.ts
  */
@@ -297,3 +307,29 @@ export interface ConduitListenResult {
   /** Duration of the listen call in milliseconds. */
   listenedForMs: number;
 }
+
+// ============================================================================
+// Typed Operation Record (T1422 — Wave D typed-dispatch)
+// ============================================================================
+
+/**
+ * Typed operation record for the conduit domain.
+ *
+ * Each key is an operation name, and each value is a tuple of
+ * `[Params, Result]` types. Used by the typed dispatch adapter
+ * (`packages/cleo/src/dispatch/adapters/typed.ts`) to provide
+ * compile-time narrowing on all conduit handler params.
+ *
+ * @task T1422 — Typed-dispatch migration (T975 follow-on)
+ * @see packages/cleo/src/dispatch/domains/conduit.ts (ConduitHandler)
+ */
+export type ConduitOps = {
+  status: [ConduitStatusParams, ConduitStatusResult];
+  peek: [ConduitPeekParams, ConduitPeekResult];
+  listen: [ConduitListenParams, ConduitListenResult];
+  start: [ConduitStartParams, ConduitStartResult];
+  stop: [ConduitStopParams, ConduitStopResult];
+  send: [ConduitSendParams, ConduitSendResult];
+  subscribe: [ConduitSubscribeParams, ConduitSubscribeResult];
+  publish: [ConduitPublishParams, ConduitPublishResult];
+};

package/src/operations/index.ts

@@ -17,6 +17,7 @@ export * from './orchestrate.js';
 export * from './params.js';
 export * from './release.js';
 export * from './research.js';
+export * from './sentient.js';
 export * from './session.js';
 export * from './skills.js';
 export * from './system.js';

package/src/operations/nexus.ts

@@ -19,7 +19,23 @@
  * @see packages/cleo/src/dispatch/domains/nexus.ts
  */
 
-import type { LAFSPage } from '../lafs.js';
+// Profile types are now canonical in nexus-user-profile.ts (T1424 dedup)
+import type {
+  NexusProfileExportParams,
+  NexusProfileExportResult,
+  NexusProfileGetParams,
+  NexusProfileGetResult,
+  NexusProfileImportParams,
+  NexusProfileImportResult,
+  NexusProfileReinforceParams,
+  NexusProfileReinforceResult,
+  NexusProfileSupersedeParams,
+  NexusProfileSupersedeResult,
+  NexusProfileUpsertParams,
+  NexusProfileUpsertResult,
+  NexusProfileViewParams,
+  NexusProfileViewResult,
+} from './nexus-user-profile.js';
 
 // ============================================================================
 // Shared Nexus wire-format types
@@ -272,8 +288,6 @@ export interface NexusListResult {
   total: number;
   /** Filtered count (post-limit). */
   filtered: number;
-  /** Pagination descriptor. */
-  page: LAFSPage;
 }
 
 // --------------------------------------------------------------------------
@@ -416,8 +430,6 @@ export interface NexusOrphansListResult {
   total: number;
   /** Filtered count. */
   filtered: number;
-  /** Pagination descriptor. */
-  page: LAFSPage;
 }
 
 // --------------------------------------------------------------------------
@@ -709,3 +721,287 @@ export interface NexusTransferResult {
   /** Manifest describing what was moved. */
   manifest: NexusTransferManifest;
 }
+
+// ============================================================================
+// Additional operations (T1424 — typed narrowing stub types)
+// ============================================================================
+
+/** Parameters for `nexus.augment`. */
+export interface NexusAugmentParams {
+  /** Search pattern (required). */
+  pattern: string;
+  /** Max results (default 5). */
+  limit?: number;
+}
+/** Result of `nexus.augment`. */
+export type NexusAugmentResult = unknown;
+
+/** Parameters for `nexus.top-entries`. */
+export interface NexusTopEntriesParams {
+  /** Max results (default 20). */
+  limit?: number;
+  /** Optional kind filter (nexus.db sources). */
+  kind?: string;
+  /** Optional nodeType filter (brain.db page_nodes). */
+  nodeType?: string;
+}
+/** Entry from brain.db. */
+export interface BrainPageNodeEntry {
+  id: string;
+  node_type: string;
+  label: string;
+  quality_score: number;
+  last_activity_at: string;
+  metadata_json: string | null;
+}
+/** Entry from nexus.db. */
+export interface NexusTopEntry {
+  nodeId: string;
+  label: string;
+  kind: string;
+  filePath: string | null;
+  totalWeight: number;
+  edgeCount: number;
+}
+/** Result of `nexus.top-entries`. */
+export interface NexusTopEntriesResult {
+  entries: BrainPageNodeEntry[] | NexusTopEntry[];
+  count: number;
+  limit: number;
+  kind?: string | null;
+  nodeType?: string | null;
+  note?: string;
+}
+
+/** Parameters for `nexus.impact`. */
+export interface NexusImpactParams {
+  /** Symbol name (required). */
+  symbol: string;
+  /** Project ID (optional, defaults to current). */
+  projectId?: string;
+  /** Include "why" reasons (optional). */
+  why?: boolean;
+}
+/** Affected symbol in impact result. */
+export interface NexusImpactAffectedNode {
+  nodeId: string;
+  label: string;
+  kind: string;
+  reasons: string[];
+}
+/** Result of `nexus.impact`. */
+export interface NexusImpactResult {
+  targetNodeId: string | null;
+  why: boolean;
+  riskLevel: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  affected: NexusImpactAffectedNode[];
+}
+
+/** Parameters for `nexus.full-context`. */
+export interface NexusFullContextParams {
+  /** Symbol name (required). */
+  symbol: string;
+}
+/** Result of `nexus.full-context`. */
+export type NexusFullContextResult = unknown;
+
+/** Parameters for `nexus.task-footprint`. */
+export interface NexusTaskFootprintParams {
+  /** Task ID (required). */
+  taskId: string;
+}
+/** Result of `nexus.task-footprint`. */
+export type NexusTaskFootprintResult = unknown;
+
+/** Parameters for `nexus.brain-anchors`. */
+export interface NexusBrainAnchorsParams {
+  /** Entry ID (required). */
+  entryId: string;
+}
+/** Result of `nexus.brain-anchors`. */
+export type NexusBrainAnchorsResult = unknown;
+
+/** Parameters for `nexus.why`. */
+export interface NexusWhyParams {
+  /** Symbol name (required). */
+  symbol: string;
+}
+/** Result of `nexus.why`. */
+export type NexusWhyResult = unknown;
+
+/** Parameters for `nexus.impact-full`. */
+export interface NexusImpactFullParams {
+  /** Symbol name (required). */
+  symbol: string;
+}
+/** Result of `nexus.impact-full`. */
+export type NexusImpactFullResult = unknown;
+
+/** Parameters for `nexus.route-map`. */
+export interface NexusRouteMapParams {
+  /** Project ID (optional, auto-generated from projectRoot). */
+  projectId?: string;
+}
+/** Result of `nexus.route-map`. */
+export type NexusRouteMapResult = unknown;
+
+/** Parameters for `nexus.shape-check`. */
+export interface NexusShapeCheckParams {
+  /** Route symbol (required). */
+  routeSymbol: string;
+  /** Project ID (optional, auto-generated from projectRoot). */
+  projectId?: string;
+}
+/** Result of `nexus.shape-check`. */
+export type NexusShapeCheckResult = unknown;
+
+/** Parameters for `nexus.search-code`. */
+export interface NexusSearchCodeParams {
+  /** Search pattern (required). */
+  pattern: string;
+  /** Max results (default 10). */
+  limit?: number;
+}
+/** Result of `nexus.search-code`. */
+export type NexusSearchCodeResult = unknown;
+
+/** Parameters for `nexus.wiki`. */
+export interface NexusWikiParams {
+  /** Output directory (optional). */
+  outputDir?: string;
+  /** Community filter (optional). */
+  communityFilter?: string;
+  /** Incremental mode (optional). */
+  incremental?: boolean;
+}
+/** Result of `nexus.wiki`. */
+export type NexusWikiResult = unknown;
+
+/** Parameters for `nexus.contracts-show`. */
+export interface NexusContractsShowParams {
+  /** Project A identifier (required). */
+  projectA: string;
+  /** Project B identifier (required). */
+  projectB: string;
+}
+/** Result of `nexus.contracts-show`. */
+export type NexusContractsShowResult = unknown;
+
+/** Parameters for `nexus.task-symbols`. */
+export interface NexusTaskSymbolsParams {
+  /** Task ID (required). */
+  taskId: string;
+}
+/** Result of `nexus.task-symbols`. */
+export type NexusTaskSymbolsResult = unknown;
+
+/** Parameters for `nexus.sigil.list`. */
+export interface NexusSigilListParams {
+  /** Role filter (optional). */
+  role?: string;
+}
+/** Result of `nexus.sigil.list`. */
+export type NexusSigilListResult = unknown;
+
+/** Parameters for `nexus.sigil.sync` — none. */
+export type NexusSigilSyncParams = Record<string, never>;
+/** Result of `nexus.sigil.sync`. */
+export type NexusSigilSyncResult = unknown;
+
+/** Parameters for `nexus.conduit-scan`. */
+export type NexusConduitScanParams = Record<string, never>;
+/** Result of `nexus.conduit-scan`. */
+export type NexusConduitScanResult = unknown;
+
+/** Parameters for `nexus.contracts-sync`. */
+export interface NexusContractsSyncParams {
+  /** Repository path (optional). */
+  repoPath?: string;
+  /** Project ID (optional). */
+  projectId?: string;
+}
+/** Result of `nexus.contracts-sync`. */
+export type NexusContractsSyncResult = unknown;
+
+/** Parameters for `nexus.contracts-link-tasks`. */
+export interface NexusContractsLinkTasksParams {
+  /** Repository path (optional). */
+  repoPath?: string;
+  /** Project ID (optional). */
+  projectId?: string;
+}
+/** Result of `nexus.contracts-link-tasks`. */
+export type NexusContractsLinkTasksResult = unknown;
+
+// ============================================================================
+// Typed Operations Union (T1424 — Wave D typed-dispatch migration)
+// ============================================================================
+
+/**
+ * All Nexus domain operations mapped to their [Params, Result] tuples.
+ *
+ * This type enables {@link TypedDomainHandler} to provide compile-time safety
+ * for every nexus operation, eliminating the ~76 type casts in the legacy
+ * handler pattern (T988 audit follow-on).
+ *
+ * @task T1424 — Nexus domain typed narrowing
+ */
+export type NexusOps = {
+  readonly status: readonly [NexusStatusParams, NexusStatusResult];
+  readonly list: readonly [NexusListParams, NexusListResult];
+  readonly show: readonly [NexusShowParams, NexusShowResult];
+  readonly resolve: readonly [NexusResolveParams, NexusResolveResult];
+  readonly deps: readonly [NexusDepsParams, NexusDepsResult];
+  readonly graph: readonly [NexusGraphParams, NexusGraphResult];
+  readonly 'path.show': readonly [NexusPathShowParams, NexusPathShowResult];
+  readonly 'blockers.show': readonly [NexusBlockersShowParams, NexusBlockersShowResult];
+  readonly 'orphans.list': readonly [NexusOrphansListParams, NexusOrphansListResult];
+  readonly discover: readonly [NexusDiscoverParams, NexusDiscoverResult];
+  readonly search: readonly [NexusSearchParams, NexusSearchResult];
+  readonly augment: readonly [NexusAugmentParams, NexusAugmentResult];
+  readonly 'share.status': readonly [NexusShareStatusParams, NexusShareStatusResult];
+  readonly 'transfer.preview': readonly [NexusTransferPreviewParams, NexusTransferPreviewResult];
+  readonly 'top-entries': readonly [NexusTopEntriesParams, NexusTopEntriesResult];
+  readonly impact: readonly [NexusImpactParams, NexusImpactResult];
+  readonly 'full-context': readonly [NexusFullContextParams, NexusFullContextResult];
+  readonly 'task-footprint': readonly [NexusTaskFootprintParams, NexusTaskFootprintResult];
+  readonly 'brain-anchors': readonly [NexusBrainAnchorsParams, NexusBrainAnchorsResult];
+  readonly why: readonly [NexusWhyParams, NexusWhyResult];
+  readonly 'impact-full': readonly [NexusImpactFullParams, NexusImpactFullResult];
+  readonly 'route-map': readonly [NexusRouteMapParams, NexusRouteMapResult];
+  readonly 'shape-check': readonly [NexusShapeCheckParams, NexusShapeCheckResult];
+  readonly 'search-code': readonly [NexusSearchCodeParams, NexusSearchCodeResult];
+  readonly wiki: readonly [NexusWikiParams, NexusWikiResult];
+  readonly 'contracts-show': readonly [NexusContractsShowParams, NexusContractsShowResult];
+  readonly 'task-symbols': readonly [NexusTaskSymbolsParams, NexusTaskSymbolsResult];
+  readonly 'profile.view': readonly [NexusProfileViewParams, NexusProfileViewResult];
+  readonly 'profile.get': readonly [NexusProfileGetParams, NexusProfileGetResult];
+  readonly 'profile.import': readonly [NexusProfileImportParams, NexusProfileImportResult];
+  readonly 'profile.export': readonly [NexusProfileExportParams, NexusProfileExportResult];
+  readonly 'profile.reinforce': readonly [NexusProfileReinforceParams, NexusProfileReinforceResult];
+  readonly 'profile.upsert': readonly [NexusProfileUpsertParams, NexusProfileUpsertResult];
+  readonly 'profile.supersede': readonly [NexusProfileSupersedeParams, NexusProfileSupersedeResult];
+  readonly 'sigil.list': readonly [NexusSigilListParams, NexusSigilListResult];
+  readonly 'sigil.sync': readonly [NexusSigilSyncParams, NexusSigilSyncResult];
+  readonly init: readonly [NexusInitParams, NexusInitResult];
+  readonly register: readonly [NexusRegisterParams, NexusRegisterResult];
+  readonly unregister: readonly [NexusUnregisterParams, NexusUnregisterResult];
+  readonly sync: readonly [NexusSyncParams, NexusSyncResult];
+  readonly 'permission.set': readonly [NexusPermissionSetParams, NexusPermissionSetResult];
+  readonly reconcile: readonly [NexusReconcileParams, NexusReconcileResult];
+  readonly 'share.snapshot.export': readonly [
+    NexusShareSnapshotExportParams,
+    NexusShareSnapshotExportResult,
+  ];
+  readonly 'share.snapshot.import': readonly [
+    NexusShareSnapshotImportParams,
+    NexusShareSnapshotImportResult,
+  ];
+  readonly transfer: readonly [NexusTransferParams, NexusTransferResult];
+  readonly 'contracts-sync': readonly [NexusContractsSyncParams, NexusContractsSyncResult];
+  readonly 'contracts-link-tasks': readonly [
+    NexusContractsLinkTasksParams,
+    NexusContractsLinkTasksResult,
+  ];
+  readonly 'conduit-scan': readonly [NexusConduitScanParams, NexusConduitScanResult];
+};

package/src/operations/release.ts

@@ -182,3 +182,90 @@ export interface ReleaseRollbackResult {
   /** Rollback reason. @task T963 */
   reason: string;
 }
+
+// ── RELEASE-03: IVTR gate check ──────────────────────────────────────────────
+
+/**
+ * Parameters for `release.gate` — checks all IVTR loops in a release epic
+ * have reached the `released` phase before allowing `release.ship`.
+ *
+ * @task T820 RELEASE-03
+ * @task T1416
+ */
+export interface ReleaseGateCheckParams {
+  /** Epic ID whose child tasks should be inspected. */
+  epicId: string;
+  /**
+   * Bypass the IVTR gate — requires explicit owner confirmation.
+   * When true, the gate check is skipped and a loud warning is emitted.
+   */
+  force?: boolean;
+}
+
+/** A single task's IVTR phase status as reported by `release.gate`. */
+export interface IvtrTaskStatus {
+  /** Task ID. */
+  taskId: string;
+  /**
+   * Current IVTR phase, or `null` when no IVTR loop has been started for
+   * this task (task is "unchecked").
+   */
+  currentPhase: 'implement' | 'validate' | 'test' | 'released' | null;
+  /** Whether the task blocks release (`true` = blocking). */
+  blocking: boolean;
+}
+
+/**
+ * Result of `release.gate`.
+ *
+ * @task T820 RELEASE-03
+ * @task T1416
+ */
+export interface ReleaseGateCheckResult {
+  /** Epic ID that was inspected. */
+  epicId: string;
+  /** Whether the gate passed — all tasks are released or unchecked. */
+  passed: boolean;
+  /** Whether the gate was bypassed via `--force`. */
+  forcedBypass: boolean;
+  /** Task IDs whose IVTR state is not `released` (blocking). */
+  blocked: string[];
+  /**
+   * Task IDs with no IVTR state (non-blocking; docs / chore tasks often
+   * have no IVTR loop).
+   */
+  unchecked: string[];
+  /** Full per-task status breakdown. */
+  tasks: IvtrTaskStatus[];
+  /**
+   * Human-readable summary suitable for CLI output and operator review.
+   * Present on both pass and fail.
+   */
+  summary: string;
+}
+
+// ── RELEASE-07: IVTR → release auto-suggest ──────────────────────────────────
+
+/**
+ * Result emitted by `release.ivtr-suggest` — the hint produced when an IVTR
+ * loop transitions to `released` and all tasks in the parent epic are now
+ * in the `released` phase.
+ *
+ * @task T820 RELEASE-07
+ * @task T1416
+ */
+export interface IvtrAutoSuggestResult {
+  /** Task ID that just reached the `released` phase. */
+  taskId: string;
+  /** Parent epic ID, if the task belongs to one. */
+  epicId: string | null;
+  /** Whether every task in the epic has reached `released`. */
+  epicFullyReleased: boolean;
+  /**
+   * Suggested next CLI command. Non-null only when `epicFullyReleased` is
+   * true. Points the operator toward `cleo release ship`.
+   */
+  suggestedCommand: string | null;
+  /** Human-readable message for operator guidance. */
+  message: string;
+}