@cleocode/contracts

@cleocode/contracts

Canonical wire-format type surface for the CLEO ecosystem. All operation Params/Result types, domain discriminated unions, LAFS envelope types, and shared primitives live here — making this package the SSoT (single source of truth) for every CLEO dispatch operation.

Position in the Architecture

@cleocode/contracts is the leaf package in the CLEO dependency graph — it has zero runtime dependencies. Every other CLEO package imports from here; nothing here imports from them.

packages/contracts/          ← wire-format SSoT (this package)
   └── src/operations/       ← <Domain>Ops discriminated unions + Params/Result types
packages/core/               ← SDK implementation (imports Params/Result from here)
packages/cleo/               ← CLI dispatch (imports XOps + OpsFromCore from here)
packages/cleo-os/            ← harness adapters (imports adapter contracts from here)
packages/studio/             ← Studio routes (imports operation types from here)

Per ADR-057 (Contracts/Core SSoT layering), every Core function that backs a dispatch operation MUST import its <Op>Params and <Op>Result types from this package. Per ADR-058 (Dispatch Type Inference via OpsFromCore<C>), dispatch handlers derive their full type-safety from these contracts rather than declaring parallel types inline.

The <Op>Params / <Op>Result Pattern

Each dispatch-ready operation is represented by a pair of types:

• <Op>Params — the wire-format input shape the CLI/Studio/SDK sends to Core.
• <Op>Result — the wire-format output shape Core returns (wrapped in a LafsEnvelope).

These pairs are collected into a <Domain>Ops discriminated union (a plain TypeScript record type). The union maps operation names to readonly [Params, Result] tuples:

// packages/contracts/src/operations/tasks.ts
export type TasksOps = {
  readonly show:     readonly [TasksShowParams,    TasksShowResult];
  readonly list:     readonly [TasksListParams,    TasksListResult];
  readonly find:     readonly [TasksFindParams,    TasksFindResult];
  readonly add:      readonly [TasksAddParams,     TasksAddResult];
  readonly update:   readonly [TasksUpdateQueryParams, TasksUpdateQueryResult];
  readonly complete: readonly [TasksCompleteQueryParams, TasksCompleteQueryResult];
  // ... (all operations in the tasks domain)
};

The dispatch layer uses TypedDomainHandler<TasksOps> to get compile-time narrowing on every branch. When a Params or Result type changes in this file, TypeScript surfaces the break immediately at every call site — no silent drift.

OpsFromCore<C> — Inference Helper

For domains where Core functions already follow the ADR-057 D1 uniform signature (async fn(projectRoot: string, params: <Op>Params): Promise<<Op>Result>), the dispatch layer can skip writing a manual <Domain>Ops type. Instead it uses OpsFromCore<C> (defined in packages/cleo/src/dispatch/adapters/typed.ts, introduced in T1436) to infer the Params/Result pairs directly from the Core function signatures:

import type { OpsFromCore } from '@cleocode/cleo/dispatch/adapters/typed';
import * as taskCore from '@cleocode/core/tasks';

// Automatically derives TasksOps-equivalent types from Core's signatures.
type InferredTasksOps = OpsFromCore<typeof taskCore>;

The contracts package supplies the Params/Result types that Core functions are annotated with — so OpsFromCore<C> and the hand-written <Domain>Ops type stay in sync automatically.

See ADR-058 for the full migration recipe, tier classification (thin wrapper / engine wrapper / manual TypedOpRecord), and escape hatches.

Usage Examples

1. Importing operation types for a tasks domain handler

import type {
  TasksOps,
  TasksAddParams,
  TasksAddResult,
  TasksShowParams,
  TasksShowResult,
} from '@cleocode/contracts';

// Use in a TypedDomainHandler — params/result are compile-time checked.
async function addTask(
  projectRoot: string,
  params: TasksAddParams,
): Promise<TasksAddResult> {
  // ...implementation...
}

2. Importing session operation types and the SessionOps union

import type {
  SessionOps,
  SessionStartParams,
  SessionStartResult,
  SessionEndParams,
  SessionEndResult,
} from '@cleocode/contracts';

// SessionOps is the discriminated union consumed by TypedDomainHandler<SessionOps>.
// Keying into it gives the exact [Params, Result] tuple for each operation.
type StartTuple = SessionOps['start'];
//   ^ readonly [SessionStartParams, SessionStartResult]

3. Working with LAFS envelopes and exit codes

import {
  isLafsSuccess,
  isLafsError,
  ExitCode,
  isSuccessCode,
  type LafsEnvelope,
} from '@cleocode/contracts';

function handleCLIResponse(response: LafsEnvelope<unknown>, code: number): void {
  if (isLafsSuccess(response)) {
    console.log('data:', response.data);
  } else if (isLafsError(response)) {
    console.error('error:', response.error.message);
  }

  if (!isSuccessCode(code)) {
    process.exit(code);
  }
}

Versioning Policy

@cleocode/contracts follows CalVer YYYY.MM.patch (e.g., 2026.4.151). The version is the calendar position of the release, not a semantic compatibility signal. Breaking changes to operation types (renamed fields, removed Params properties) are tracked via ADR entries and announced in the CHANGELOG. Consumers should pin to a specific version and review the CHANGELOG on upgrades.

The package is published to npm with "access": "public" — see publishConfig in package.json. It is not marked "private".

Sub-path Exports

The package exposes several sub-path entry points in addition to the root ".":

Sub-path	Contents
. (root)	All domain types, LAFS envelope types, exit codes, status registry, and re-exported operation types (ops.*, TasksOps, SessionOps, …)
./operations/*	Individual operation files by domain (e.g., ./operations/tasks, ./operations/session)
./nexus-contract-ops	Nexus contract operation types
./nexus-living-brain-ops	BRAIN super-domain living-brain operation types
./nexus-query-ops	Nexus query operation types
./nexus-route-ops	Nexus route operation types
./nexus-tasks-bridge-ops	Nexus–Tasks bridge operation types

Example:

// Root import — preferred for most consumers
import type { TasksOps, TasksAddParams } from '@cleocode/contracts';

// Sub-path import — useful when you need tree-shaking at the type level
import type { TasksOps } from '@cleocode/contracts/operations/tasks';

ADR Cross-References

ADR	Topic
ADR-057	Contracts/Core SSoT layering — uniform (projectRoot, params) Core API and OpsFromCore-inferred dispatch
ADR-058	Dispatch type inference via OpsFromCore<C> — pattern, migration recipe, escape hatches
ADR-039	LAFS envelope format — LafsEnvelope<T>, LafsSuccess, LafsError
ADR-056	DB SSoT layering (supplements the contracts SSoT for storage types)

API Overview

Operation Types (Wire Format)

All domains follow the <Op>Params / <Op>Result naming convention. Available domain operation files under src/operations/:

Domain file	XOps type	Description
tasks.ts	TasksOps	Task CRUD, query, lifecycle, sync, claim
session.ts	SessionOps	Session start/end/resume, briefing, handoff
brain.ts	—	BRAIN super-graph wire types
memory.ts	MemoryOps	Observations, patterns, decisions, tiers
nexus.ts	NexusOps	Code intelligence, wiki, impact
lifecycle.ts	LifecycleOps	Epic lifecycle pipeline stages
orchestrate.ts	OrchestrateOps	Multi-agent spawn, wave, IVTR, playbook
pipeline.ts	—	LOOM pipeline wave types
admin.ts	AdminOps	Backup, restore, export, import
validate.ts	CheckOps	Evidence gates, verification
release.ts	ReleaseOps	CalVer release and tag
sentient.ts	SentientOps	Tier-2 proposal management
conduit.ts	ConduitOps	Messaging transport
research.ts	ResearchOps	LOOM research stage
skills.ts	SkillsOps	Agent skill management
playbook.ts	PlaybookOps	.cantbook playbook execution
worktree.ts	WorktreeOps	Git worktree provisioning
issues.ts	IssuesOps	GitHub issue sync
system.ts	SystemOps	System health and diagnostics
sticky.ts	StickyOps	Sticky note capture

LAFS Envelope Types

Standardized response envelope (per ADR-039):

import type { LafsEnvelope, LafsSuccess, LafsError } from '@cleocode/contracts';
import { isLafsSuccess, isLafsError } from '@cleocode/contracts';

Core Domain Types

import type {
  Task, TaskCreate, TaskPriority, TaskStatus, TaskType, TaskSize,
  Session, SessionScope,
  DataAccessor, TransactionAccessor,
  CleoConfig,
  BrainEntryRef,
  CLEOProviderAdapter,
} from '@cleocode/contracts';

Status Registry

import {
  TASK_STATUSES,
  isValidStatus,
  TASK_STATUS_SYMBOLS_UNICODE,
} from '@cleocode/contracts';

Exit Codes

import { ExitCode, isSuccessCode, isErrorCode, getExitCodeName } from '@cleocode/contracts';

Dependencies

This package has no runtime dependencies. It is a pure TypeScript type and constant library. The only dev dependency is vitest for schema validation tests.

License

MIT — see LICENSE for details.