@cleocode/contracts 2026.5.2 → 2026.5.4

package/src/lafs.ts

@@ -1,175 +1,44 @@
 /**
  * LAFS (LLM-Agent-First Schema) unified envelope types.
  *
- * Defines canonical LAFS types inline (contracts has ZERO external dependencies).
- * In the main CLEO codebase these are re-exported from @cleocode/lafs;
- * here they are defined as plain interfaces for maximum portability.
+ * Protocol-level types (`LAFSEnvelope`, `LAFSMeta`, `LAFSError`,
+ * `LAFSErrorCategory`, `LAFSTransport`, `LAFSPage*`, `MVILevel`, `Warning`)
+ * are owned by `@cleocode/lafs` (ADR-039) and re-exported here so that
+ * downstream consumers can import from a single well-known contracts path.
+ *
+ * Contracts-specific types (`LafsEnvelope`, `LafsSuccess`, `LafsError`,
+ * `LafsErrorDetail`, `LafsAlternative`, `GatewayMeta`, `GatewayEnvelope`,
+ * `CleoResponse`) are defined here because they represent CLEO's CLI-layer
+ * and gateway-layer response contracts that depend on the protocol types but
+ * are not part of the LAFS SDK itself.
  *
  * @epic T4654
- * @task T4655
+ * @task T1706
  */
 
 // ---------------------------------------------------------------------------
-// Canonical LAFS types (inlined from @cleocode/lafs)
+// Re-export canonical LAFS protocol types from @cleocode/lafs (ADR-039)
 // ---------------------------------------------------------------------------
 
-/** LAFS error category. */
-export type LAFSErrorCategory =
-  | 'validation'
-  | 'not_found'
-  | 'conflict'
-  | 'authorization'
-  | 'internal'
-  | 'rate_limit'
-  | 'timeout'
-  | 'dependency';
-
-/** LAFS error object. */
-export interface LAFSError {
-  /** Stable error code (numeric HTTP status or string identifier). */
-  code: number | string;
-  /** High-level error classification category. */
-  category: LAFSErrorCategory;
-  /** Human-readable error description. */
-  message: string;
-  /**
-   * Suggested fix or recovery action for the caller.
-   *
-   * @defaultValue undefined
-   */
-  fix?: string;
-  /**
-   * Arbitrary key-value pairs with additional error context.
-   *
-   * @defaultValue undefined
-   */
-  details?: Record<string, unknown>;
-}
-
-/** LAFS warning. */
-export interface Warning {
-  /** Machine-readable warning code. */
-  code: string;
-  /** Human-readable warning description. */
-  message: string;
-}
-
-/** LAFS transport metadata. */
-export type LAFSTransport = 'cli' | 'http' | 'sdk';
-
-/** MVI (Minimal Viable Information) level. */
-export type MVILevel = 'minimal' | 'standard' | 'full';
-
-/**
- * LAFS page — no pagination.
- *
- * Discriminator field is `mode` to match the canonical {@link "@cleocode/lafs"}
- * spec (LAFSPageNone). Contracts cannot depend on `@cleocode/lafs` directly
- * (zero external deps invariant) so the type is inlined with matching shape.
- */
-export interface LAFSPageNone {
-  /** Discriminant indicating no pagination. */
-  mode: 'none';
-}
-
-/**
- * LAFS page — offset-based pagination.
- *
- * Discriminator field is `mode` to match the canonical {@link "@cleocode/lafs"}
- * spec (LAFSPageOffset).
- */
-export interface LAFSPageOffset {
-  /** Discriminant identifying offset-based pagination. */
-  mode: 'offset';
-  /** Maximum number of items per page. */
-  limit: number;
-  /** Zero-based index of the first item in this page. */
-  offset: number;
-  /** Whether additional pages exist beyond the current one. */
-  hasMore: boolean;
-  /** Total number of items across all pages, or `null` if unknown. */
-  total?: number | null;
-}
-
-/**
- * LAFS page — cursor-based pagination.
- *
- * Discriminator field is `mode` to match the canonical {@link "@cleocode/lafs"}
- * spec (LAFSPageCursor).
- */
-export interface LAFSPageCursor {
-  /** Discriminant identifying cursor-based pagination. */
-  mode: 'cursor';
-  /** Opaque cursor for fetching the next page, or `null` when at the end. */
-  nextCursor: string | null;
-  /** Whether additional pages exist beyond the current one. */
-  hasMore: boolean;
-  /** Maximum number of items per page. */
-  limit?: number;
-  /** Total number of items across all pages, or `null` if unknown. */
-  total?: number | null;
-}
-
-/**
- * LAFS page union.
- *
- * Structurally compatible with `@cleocode/lafs` `LAFSPage` so that values
- * flow freely between dispatch (which uses contracts) and core (which uses
- * lafs). Both export the same three variants discriminated on `mode`.
- */
-export type LAFSPage = LAFSPageNone | LAFSPageOffset | LAFSPageCursor;
+export type {
+  LAFSEnvelope,
+  LAFSError,
+  LAFSErrorCategory,
+  LAFSMeta,
+  LAFSPage,
+  LAFSPageCursor,
+  LAFSPageNone,
+  LAFSPageOffset,
+  LAFSTransport,
+  MVILevel,
+  Warning,
+} from '@cleocode/lafs';
 
-/** LAFS metadata block. */
-export interface LAFSMeta {
-  /** Transport protocol used for this envelope. */
-  transport: LAFSTransport;
-  /** Minimum Viable Information level controlling verbosity. */
-  mvi: MVILevel;
-  /**
-   * Pagination metadata when the result is a paginated collection.
-   *
-   * @defaultValue undefined
-   */
-  page?: LAFSPage;
-  /**
-   * Non-fatal warnings to surface to the consuming agent.
-   *
-   * @defaultValue undefined
-   */
-  warnings?: Warning[];
-  /**
-   * Operation duration in milliseconds.
-   *
-   * @defaultValue undefined
-   */
-  durationMs?: number;
-}
-
-/** LAFS envelope (canonical protocol type). */
-export interface LAFSEnvelope<T = unknown> {
-  /** Whether the operation completed successfully. */
-  success: boolean;
-  /**
-   * Operation result payload on success.
-   *
-   * @defaultValue undefined
-   */
-  data?: T;
-  /**
-   * Structured error payload on failure.
-   *
-   * @defaultValue undefined
-   */
-  error?: LAFSError;
-  /**
-   * Protocol and transport metadata.
-   *
-   * @defaultValue undefined
-   */
-  _meta?: LAFSMeta;
-}
+// ---------------------------------------------------------------------------
+// Contracts-specific types (not part of the LAFS SDK)
+// ---------------------------------------------------------------------------
 
-/** Flag input for conformance checks. */
+/** Input for conformance checks. */
 export interface FlagInput {
   /** Name of the flag being checked. */
   flag: string;
@@ -267,12 +136,15 @@ export interface LafsError {
 export type LafsEnvelope<T = unknown> = LafsSuccess<T> | LafsError;
 
 // ---------------------------------------------------------------------------
-// Gateway envelope extension (extends LAFSMeta)
+// Gateway envelope extension (extends LAFSMeta from @cleocode/lafs)
 // ---------------------------------------------------------------------------
 
+import type { LAFSMeta } from '@cleocode/lafs';
+
 /**
  * Metadata attached to every gateway response.
- * Extends the canonical LAFSMeta with CLEO gateway-specific fields.
+ * Extends the canonical LAFSMeta from @cleocode/lafs with CLEO
+ * gateway-specific fields.
  *
  * @task T4655
  */

package/src/operations/conduit.ts

@@ -184,8 +184,21 @@ export interface ConduitSendParams {
   /** Send as this agent. Omit to use the active agent from the registry. */
   agentId?: string;
 }
-/** Result of `conduit.send`. */
-export interface ConduitSendResult {
+
+/**
+ * Operation result of `conduit.send`.
+ *
+ * @remarks
+ * This is the wire-format result for the `conduit.send` CLI/HTTP dispatch
+ * operation. It carries transport metadata (`from`, `to`, `transport`,
+ * `sentAt`) not present in the transport-layer {@link ConduitSendResult}
+ * defined in `../conduit.ts`.
+ *
+ * The transport-layer type (`@cleocode/contracts` top-level `ConduitSendResult`)
+ * covers the `Conduit` interface (ConduitClient / publishToTopic). This type
+ * covers the CLI dispatch surface.
+ */
+export interface ConduitSendOperationResult {
   /** The assigned message id. */
   messageId: string;
   /** Sender agent id. */
@@ -329,7 +342,7 @@ export type ConduitOps = {
   listen: [ConduitListenParams, ConduitListenResult];
   start: [ConduitStartParams, ConduitStartResult];
   stop: [ConduitStopParams, ConduitStopResult];
-  send: [ConduitSendParams, ConduitSendResult];
+  send: [ConduitSendParams, ConduitSendOperationResult];
   subscribe: [ConduitSubscribeParams, ConduitSubscribeResult];
   publish: [ConduitPublishParams, ConduitPublishResult];
 };

package/src/operations/docs.ts

@@ -28,6 +28,8 @@
  * @see packages/contracts/src/operations/index.ts
  */
 
+import type { AttachmentKind } from '../attachment.js';
+
 // ============================================================================
 // Shared Attachment Types (API wire format)
 // ============================================================================
@@ -45,22 +47,26 @@ export type AttachmentOwnerType =
   | 'learning'
   | 'pattern';
 
-/**
- * Supported attachment kind (storage mode).
- *
- * - `local-file` — file path tracked in metadata; bytes stored in blob
- * - `blob`       — inline content uploaded; bytes stored in blob
- * - `url`        — URL-only reference; no bytes stored
- * - `llms-txt`   — generated content from `docs.generate --attach`
- */
-export type AttachmentKind = 'local-file' | 'blob' | 'url' | 'llms-txt';
+// Re-export the canonical AttachmentKind so consumers of this module do not
+// need a separate import from `../attachment.js`.
+export type { AttachmentKind } from '../attachment.js';
 
 /**
- * Attachment metadata fragment returned by query operations.
+ * Flattened wire-format attachment row returned by docs query operations.
+ *
+ * This is the **API response shape** — a denormalised projection of the domain
+ * {@link import('../attachment.js').AttachmentMetadata} registry row suitable for
+ * CLI/HTTP serialisation.  Key differences from the domain type:
+ *
+ * - `kind` is lifted from the nested `attachment` object to the top level.
+ * - `mime` and `size` are lifted and made optional (not all kinds carry them).
+ * - The full `attachment` discriminated-union value is NOT included (too verbose
+ *   for list/fetch wire responses).
  *
- * Includes kind, mime type, size (when applicable), description, and labels.
+ * @see {@link import('../attachment.js').AttachmentMetadata} — the full domain
+ *   registry row stored in `.cleo/attachments/index.db`.
  */
-export interface AttachmentMetadata {
+export interface DocsAttachmentRow {
   /** Attachment identifier (UUID-like string). */
   id: string;
   /** SHA-256 hash of content; truncated to 8 chars in list views. */
@@ -96,7 +102,7 @@ export type AttachmentBackend = 'legacy' | 'llmstxt-v2';
  */
 export interface AttachmentRecord {
   /** Attachment metadata. */
-  metadata: AttachmentMetadata;
+  metadata: DocsAttachmentRow;
   /** File system path where bytes are stored (if applicable). */
   path?: string;
   /** Size in bytes. */
@@ -140,7 +146,7 @@ export interface DocsListResult {
   /** Count of attachments for this owner. */
   count: number;
   /** Attachment metadata array. */
-  attachments: AttachmentMetadata[];
+  attachments: DocsAttachmentRow[];
   /** Current attachment backend in use. */
   attachmentBackend?: AttachmentBackend;
 }
@@ -161,8 +167,8 @@ export interface DocsFetchParams {
  * Result of `docs.fetch`.
  */
 export interface DocsFetchResult {
-  /** Attachment record with metadata and optional inline bytes. */
-  metadata: AttachmentMetadata;
+  /** Flattened attachment metadata row for this attachment. */
+  metadata: DocsAttachmentRow;
   /** File system path where bytes are stored (if applicable). */
   path?: string;
   /** Total size in bytes. */

package/src/operations/index.ts

@@ -5,8 +5,12 @@
  * to avoid name collisions with canonical domain types.
  */
 
+export * from './admin.js';
 export * from './brain.js';
 export * from './conduit.js';
+export * from './dialectic.js';
+export * from './docs.js';
+export * from './intelligence.js';
 export * from './issues.js';
 export * from './lifecycle.js';
 export * from './llm.js';
@@ -22,6 +26,7 @@ export * from './research.js';
 export * from './sentient.js';
 export * from './session.js';
 export * from './skills.js';
+export * from './sticky.js';
 export * from './system.js';
 export * from './tasks.js';
 export * from './validate.js';

package/src/operations/lifecycle.ts

@@ -5,9 +5,9 @@
  * Mutate operations: 5
  */
 
-import type { StageStatus } from '../status-registry.js';
+import type { GateStatus, StageStatus } from '../status-registry.js';
 
-export type { StageStatus };
+export type { GateStatus, StageStatus };
 
 /**
  * Common lifecycle types
@@ -23,8 +23,6 @@ export type LifecycleStage =
   | 'testing'
   | 'release';
 
-export type GateStatus = 'passed' | 'failed' | 'blocked' | null;
-
 export interface StageRecord {
   stage: LifecycleStage;
   status: StageStatus;
@@ -85,7 +83,7 @@ export interface LifecycleCheckResult {
   /** Ordered list of stages that must complete first. @task T963 */
   missingPrerequisites: LifecycleStage[];
   /** Current gate status for the target stage. @task T963 */
-  gateStatus: 'passed' | 'failed' | 'pending';
+  gateStatus: GateStatus;
 }
 
 // lifecycle.status