@cleocode/contracts 2026.4.100 → 2026.4.101

package/src/operations/brain.ts

@@ -21,12 +21,13 @@
  * `Record<string, unknown>` is legitimate — super-graph callers treat
  * it opaquely; individual substrate adapters own the concrete shape.
  *
- * SYNC: Canonical runtime implementation now lives at
- * `@cleocode/brain` (BrainNode, BrainEdge, BrainGraph, adapters, SSE
- * stream). The runtime shapes there are intentionally structurally
- * distinct from these wire-format contracts — runtime `BrainNode` uses
- * `kind: BrainNodeKind` + `meta` + optional adapter-produced `weight`,
- * whereas contract `BrainNode` below uses `type: string` + `data`.
+ * SYNC: Canonical runtime shapes (`BrainNode`, `BrainEdge`, `BrainGraph`)
+ * live at `packages/contracts/src/brain-graph.ts` (T989 unification).
+ * The types in this file are **wire-format only** and are named with a
+ * `Wire` suffix (`BrainNodeWire`, `BrainEdgeWire`, `BrainStreamEventWire`)
+ * to prevent collision with the canonical runtime types. Runtime
+ * `BrainNode` uses `kind: BrainNodeKind` + `meta` + optional `weight`,
+ * whereas `BrainNodeWire` uses `type: string` + `data`.
  *
  * @task T962 — Orchestration Coherence v4 (BRAIN super-domain)
  * @task T968 — operations/brain.ts contract authoring (Wave B)
@@ -120,8 +121,10 @@ export type BrainEdgeKind =
  * statically-typed payload belongs inside each substrate adapter.
  *
  * @task T962 / T968
+ * @remarks Wire-format type. The canonical runtime shape is {@link BrainNode}
+ *   from `@cleocode/contracts` (`packages/contracts/src/brain-graph.ts`).
  */
-export interface BrainNode {
+export interface BrainNodeWire {
   /** Substrate-prefixed identifier (see {@link BrainNodeId}). */
   id: BrainNodeId;
   /** Source substrate. */
@@ -149,9 +152,12 @@ export interface BrainNode {
  * in-substrate (both endpoints share the same prefix) or cross-substrate
  * (bridges between e.g. `memory:…` and `nexus:…`).
  *
+ * Wire-format type. The canonical runtime shape is {@link BrainEdge}
+ * from `@cleocode/contracts` (`packages/contracts/src/brain-graph.ts`).
+ *
  * @task T962 / T968
  */
-export interface BrainEdge {
+export interface BrainEdgeWire {
   /** Source node id. */
   from: BrainNodeId;
   /** Target node id. */
@@ -234,9 +240,9 @@ export interface BrainQueryParams {
  */
 export interface BrainQueryResult {
   /** Merged, deduplicated nodes across substrates. */
-  nodes: BrainNode[];
+  nodes: BrainNodeWire[];
   /** Edges (may reference stub nodes injected for cross-substrate targets). */
-  edges: BrainEdge[];
+  edges: BrainEdgeWire[];
   /** Aggregate and per-substrate counters. */
   stats: {
     /** Per-substrate node/edge contribution. */
@@ -273,13 +279,13 @@ export interface BrainNodeParams {
  */
 export interface BrainNodeResult {
   /** The requested node. */
-  node: BrainNode;
+  node: BrainNodeWire;
   /** Neighbour edges partitioned by direction relative to `node.id`. */
   neighbors: {
     /** Edges whose `to` equals the requested node. */
-    inbound: BrainEdge[];
+    inbound: BrainEdgeWire[];
     /** Edges whose `from` equals the requested node. */
-    outbound: BrainEdge[];
+    outbound: BrainEdgeWire[];
   };
 }
 
@@ -315,9 +321,9 @@ export interface BrainSubstrateResult {
   /** The substrate that was projected. */
   substrate: BrainSubstrateName;
   /** Nodes contributed by this substrate. */
-  nodes: BrainNode[];
+  nodes: BrainNodeWire[];
   /** Edges contributed by this substrate. */
-  edges: BrainEdge[];
+  edges: BrainEdgeWire[];
   /** True when the result was capped by `limit`. */
   truncated: boolean;
 }
@@ -343,16 +349,18 @@ export interface BrainSubstrateResult {
  * - `task.status`    — shortcut for tasks-substrate status changes.
  * - `message.send`   — shortcut for conduit-substrate message inserts.
  *
- * Mirrors `@cleocode/brain :: BrainStreamEvent` with super-graph-aligned
- * identifiers (ids are substrate-prefixed).
+ * Wire-format event union. The canonical runtime event type is
+ * `{@link BrainStreamEvent}` from `@cleocode/contracts` (`brain-graph.ts`).
+ * The main difference: wire-format uses `from`/`to`/`kind` for edge events,
+ * runtime uses `fromId`/`toId`/`edgeType` for compatibility with studio SSE.
  *
  * @task T962 / T968
  */
-export type BrainStreamEvent =
+export type BrainStreamEventWire =
   | { type: 'hello'; ts: string }
   | { type: 'heartbeat'; ts: string }
-  | { type: 'node.create'; node: BrainNode; ts: string }
-  | { type: 'node.update'; node: BrainNode; ts: string }
+  | { type: 'node.create'; node: BrainNodeWire; ts: string }
+  | { type: 'node.update'; node: BrainNodeWire; ts: string }
   | {
       type: 'edge.strengthen';
       from: BrainNodeId;
@@ -393,7 +401,7 @@ export interface BrainStreamParams {
   /** Restrict events to these substrates. Default: all. */
   substrates?: BrainSubstrateName[];
   /** Restrict to these event kinds (e.g. `['node.create', 'edge.strengthen']`). */
-  kinds?: Array<BrainStreamEvent['type']>;
+  kinds?: Array<BrainStreamEventWire['type']>;
   /**
    * ISO 8601 resume cursor. When set, the server replays events emitted
    * at or after `sinceTs` before tailing the live stream.
@@ -414,7 +422,7 @@ export interface BrainStreamParams {
  */
 export interface BrainStreamResult {
   /** One decoded SSE frame. */
-  event: BrainStreamEvent;
+  event: BrainStreamEventWire;
 }
 
 // ============================================================================
@@ -455,7 +463,7 @@ export interface BrainBridgesParams {
  */
 export interface BrainBridgesResult {
   /** Cross-substrate edges matching the query. */
-  bridges: BrainEdge[];
+  bridges: BrainEdgeWire[];
   /** Per-pair counts keyed by `"${fromSubstrate}->${toSubstrate}"`. */
   pairCounts: Record<string, number>;
   /** Total bridges returned. */
@@ -498,7 +506,7 @@ export interface BrainNeighborhoodParams {
  */
 export interface BrainNeighborhoodNode {
   /** The visited node. */
-  node: BrainNode;
+  node: BrainNodeWire;
   /** BFS distance from the seed (`0` = seed itself). */
   depth: number;
 }
@@ -514,7 +522,7 @@ export interface BrainNeighborhoodResult {
   /** Nodes visited, annotated with BFS depth. */
   nodes: BrainNeighborhoodNode[];
   /** Edges traversed during expansion. */
-  edges: BrainEdge[];
+  edges: BrainEdgeWire[];
   /** Maximum depth actually reached (≤ requested `hops`). */
   reachedDepth: number;
   /** True when the traversal was capped by `maxNodes`. */
@@ -554,7 +562,7 @@ export interface BrainSearchParams {
  */
 export interface BrainSearchHit {
   /** The matched node. */
-  node: BrainNode;
+  node: BrainNodeWire;
   /** Normalised relevance in `[0, 1]`. Higher = better. */
   score: number;
   /** Which substrate contributed this hit. */

package/src/operations/docs.ts

@@ -0,0 +1,322 @@
+/**
+ * Docs Domain Operations Contract (5 operations)
+ *
+ * Query operations: 3
+ * Mutate operations: 2
+ *
+ * Docs domain handles attachment management and document generation via `cleo docs`:
+ *   - add     — attach a local file or URL to a CLEO owner entity (task, session, observation)
+ *   - list    — list attachments for an owner entity
+ *   - generate — generate llms.txt summary for a task/epic, optionally attach as blob
+ *   - fetch   — retrieve attachment bytes and metadata by ID or SHA-256
+ *   - remove  — remove an attachment ref; purges blob when refCount hits zero
+ *
+ * Owner type is auto-detected from the owner ID prefix:
+ *   T###        → 'task'
+ *   ses_*       → 'session'
+ *   O-*         → 'observation'
+ *   D-* (dec_*) → 'decision'
+ *   L-* (lrn_*) → 'learning'
+ *   P-* (pat_*) → 'pattern'
+ *   (default)   → 'task'
+ *
+ * SYNC: Canonical implementations at packages/core/src/store/attachment*.
+ * Wire-format types live here; they are the API contract for CLI + HTTP dispatch.
+ *
+ * @task T980 — Orchestration Coherence v4 (contract surface completion)
+ * @see packages/cleo/src/dispatch/domains/docs.ts
+ * @see packages/contracts/src/operations/index.ts
+ */
+
+// ============================================================================
+// Shared Attachment Types (API wire format)
+// ============================================================================
+
+/**
+ * Supported attachment owner type.
+ *
+ * Inferred from owner ID prefix; controls which table attachment refs are stored in.
+ */
+export type AttachmentOwnerType =
+  | 'task'
+  | 'session'
+  | 'observation'
+  | 'decision'
+  | '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';
+
+/**
+ * Attachment metadata fragment returned by query operations.
+ *
+ * Includes kind, mime type, size (when applicable), description, and labels.
+ */
+export interface AttachmentMetadata {
+  /** Attachment identifier (UUID-like string). */
+  id: string;
+  /** SHA-256 hash of content; truncated to 8 chars in list views. */
+  sha256: string;
+  /** Attachment kind / storage mode. */
+  kind: AttachmentKind;
+  /** MIME type (when applicable; omitted for url kind). */
+  mime?: string;
+  /** Content size in bytes (only for local-file and blob kinds). */
+  size?: number;
+  /** Optional human-readable description. */
+  description?: string;
+  /** Optional labels array for categorization. */
+  labels?: string[];
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+  /** Current reference count across all owners. */
+  refCount: number;
+}
+
+/**
+ * Supported attachment backend.
+ *
+ * - `legacy` — original file-based store (.cleo/attachments)
+ * - `llmstxt-v2` — llmtxt-backed manifest store
+ */
+export type AttachmentBackend = 'legacy' | 'llmstxt-v2';
+
+/**
+ * Detailed attachment record with full metadata and optional byte content.
+ *
+ * Returned by `docs.fetch` operation.
+ */
+export interface AttachmentRecord {
+  /** Attachment metadata. */
+  metadata: AttachmentMetadata;
+  /** File system path where bytes are stored (if applicable). */
+  path?: string;
+  /** Size in bytes. */
+  sizeBytes: number;
+  /** Base64-encoded content (only for attachments <= 1 MB). */
+  bytesBase64?: string;
+  /** True when bytesBase64 is populated. */
+  inlined: boolean;
+}
+
+// ============================================================================
+// Query Operations
+// ============================================================================
+
+// --------------------------------------------------------------------------
+// docs.list — list attachments for an owner
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.list`.
+ *
+ * Exactly one of `task`, `session`, or `observation` must be provided.
+ */
+export interface DocsListParams {
+  /** Task identifier to list attachments for. */
+  task?: string;
+  /** Session identifier to list attachments for. */
+  session?: string;
+  /** Observation identifier to list attachments for. */
+  observation?: string;
+}
+
+/**
+ * Result of `docs.list`.
+ */
+export interface DocsListResult {
+  /** Owner entity ID. */
+  ownerId: string;
+  /** Inferred owner type. */
+  ownerType: AttachmentOwnerType;
+  /** Count of attachments for this owner. */
+  count: number;
+  /** Attachment metadata array. */
+  attachments: AttachmentMetadata[];
+  /** Current attachment backend in use. */
+  attachmentBackend?: AttachmentBackend;
+}
+
+// --------------------------------------------------------------------------
+// docs.fetch — retrieve attachment bytes and metadata by ID or SHA-256
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.fetch`.
+ */
+export interface DocsFetchParams {
+  /** Attachment reference: attachment ID or SHA-256 hex string (required). */
+  attachmentRef: string;
+}
+
+/**
+ * Result of `docs.fetch`.
+ */
+export interface DocsFetchResult {
+  /** Attachment record with metadata and optional inline bytes. */
+  metadata: AttachmentMetadata;
+  /** File system path where bytes are stored (if applicable). */
+  path?: string;
+  /** Total size in bytes. */
+  sizeBytes: number;
+  /** Base64-encoded content (only for attachments <= 1 MB). */
+  bytesBase64?: string;
+  /** True when bytesBase64 is populated. */
+  inlined: boolean;
+  /** Current attachment backend in use. */
+  attachmentBackend?: AttachmentBackend;
+}
+
+// --------------------------------------------------------------------------
+// docs.generate — generate llms.txt summary and optionally attach
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.generate`.
+ */
+export interface DocsGenerateParams {
+  /** Task or epic ID to generate llms.txt for (required). */
+  for: string;
+  /** When true, attach the generated content as a blob (optional). */
+  attach?: boolean;
+}
+
+/**
+ * Result of `docs.generate`.
+ */
+export interface DocsGenerateResult {
+  /** ID of the task/epic that was summarized. */
+  forId: string;
+  /** Generated llms.txt content. */
+  content: string;
+  /** Count of attachments that were included in the summary. */
+  attachmentCount: number;
+  /** True when the llmtxt package was used (false = fallback). */
+  usedLlmtxtPackage: boolean;
+  /** True when --attach was specified and attachment succeeded. */
+  attached: boolean;
+  /** Attachment ID if attached (when `attached === true`). */
+  attachmentId?: string;
+  /** SHA-256 hash of attachment if attached (when `attached === true`). */
+  attachmentSha256?: string;
+}
+
+// ============================================================================
+// Mutate Operations
+// ============================================================================
+
+// --------------------------------------------------------------------------
+// docs.add — attach a local file or URL to an owner
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.add`.
+ *
+ * Exactly one of `file` or `url` must be provided.
+ */
+export interface DocsAddParams {
+  /** Owner entity ID (task, session, observation, etc.) — required. */
+  ownerId: string;
+  /** Local file path to attach (mutually exclusive with `url`). */
+  file?: string;
+  /** URL to attach as reference (mutually exclusive with `file`). */
+  url?: string;
+  /** Optional human-readable description. */
+  desc?: string;
+  /** Optional comma-separated labels for categorization. */
+  labels?: string;
+  /** Agent or service that attached this file (default: 'human'). */
+  attachedBy?: string;
+}
+
+/**
+ * Result of `docs.add`.
+ */
+export interface DocsAddResult {
+  /** Newly-created or existing attachment ID. */
+  attachmentId: string;
+  /** SHA-256 hash of the attached content. */
+  sha256: string;
+  /** Current reference count for this attachment. */
+  refCount: number;
+  /** Attachment kind that was stored. */
+  kind: AttachmentKind;
+  /** Owner entity ID. */
+  ownerId: string;
+  /** Inferred owner type. */
+  ownerType: AttachmentOwnerType;
+  /** URL if `kind === 'url'` (otherwise omitted). */
+  url?: string;
+  /** Current attachment backend in use. */
+  attachmentBackend?: AttachmentBackend;
+}
+
+// --------------------------------------------------------------------------
+// docs.remove — remove an attachment ref
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `docs.remove`.
+ */
+export interface DocsRemoveParams {
+  /** Attachment reference: attachment ID or SHA-256 hex (required). */
+  attachmentRef: string;
+  /** Owner entity ID to remove the ref from (required). */
+  from: string;
+}
+
+/**
+ * Result of `docs.remove`.
+ */
+export interface DocsRemoveResult {
+  /** True when the attachment blob was fully purged (refCount hit zero). */
+  removed: boolean;
+  /** Attachment ID that was dereferenced. */
+  attachmentId: string;
+  /** Owner entity ID. */
+  from: string;
+  /** Reference count after dereference (0 if blob was purged). */
+  refCountAfter: number;
+  /** True when blob was purged (duplicate of `removed` for clarity). */
+  blobPurged: boolean;
+  /** Current attachment backend in use. */
+  attachmentBackend?: AttachmentBackend;
+}
+
+// ============================================================================
+// Discriminated Union (DocsOps)
+// ============================================================================
+
+/**
+ * Discriminated union of all docs domain operations.
+ *
+ * Consumed by `packages/cleo/src/dispatch/domains/docs.ts` via `TypedDomainHandler<DocsOps>`.
+ *
+ * @remarks
+ * Pattern: each variant specifies `op` (operation name), `params` (input),
+ * and `result` (output). The dispatch layer uses the `op` discriminator to
+ * route to the correct handler method and validate types.
+ */
+export type DocsOps =
+  | { op: 'docs.list'; params: DocsListParams; result: DocsListResult }
+  | { op: 'docs.fetch'; params: DocsFetchParams; result: DocsFetchResult }
+  | { op: 'docs.generate'; params: DocsGenerateParams; result: DocsGenerateResult }
+  | { op: 'docs.add'; params: DocsAddParams; result: DocsAddResult }
+  | { op: 'docs.remove'; params: DocsRemoveParams; result: DocsRemoveResult };
+
+/**
+ * Enumeration of all docs domain operation names.
+ *
+ * @remarks
+ * Useful for dynamic operation dispatch, type narrowing, or documentation.
+ * Kept in sync with the `DocsOps` discriminated union above.
+ */
+export type DocsOp = 'docs.list' | 'docs.fetch' | 'docs.generate' | 'docs.add' | 'docs.remove';