@cleocode/contracts 2026.4.100 → 2026.4.102

package/src/operations/session.ts

@@ -1,16 +1,24 @@
 /**
- * Session Domain Operations (9 operations)
+ * Session Domain Operations (15 operations)
  *
- * Query operations: 4
- * Mutate operations: 5
+ * Query operations: 8 (status, list, show, find, decision.log, context.drift, handoff.show, briefing.show)
+ * Mutate operations: 7 (start, end, resume, suspend, gc, record.decision, record.assumption)
  *
- * SYNC: Canonical type definitions live in the CLI package at:
- *   src/types/session.ts (Session, SessionScope, etc.)
- * These operation types are the API contract (wire format).
+ * SYNC: Canonical domain types live in packages/contracts/src/session.ts.
+ * These operation types are the API contract (wire format) for the dispatch layer.
+ *
+ * @task T975 — typed-dispatch migration (Wave D · T962)
  */
 
+import type { Session } from '../session.js';
+
+// ---------------------------------------------------------------------------
+// Common session types (simplified wire-format representation)
+// ---------------------------------------------------------------------------
+
 /**
- * Common session types
+ * Minimal session representation for wire-format responses.
+ * Used in results that return simplified session data.
  */
 export interface SessionOp {
   id: string;
@@ -23,64 +31,151 @@ export interface SessionOp {
   notes?: string[];
 }
 
-/**
- * Query Operations
- */
+// ---------------------------------------------------------------------------
+// Query Operations
+// ---------------------------------------------------------------------------
 
 // session.status
+/** Parameters for `session.status` — no params required. */
 export type SessionStatusParams = Record<string, never>;
+
 /**
  * Result of `session.status`.
  *
  * @remarks
  * Re-synced to match the envelope returned by `sessionStatus` in
- * `packages/cleo/src/dispatch/engines/session-engine.ts`. The legacy
- * contract's `{current, hasStartedTask, startedTask}` shape predated the
- * current engine and never matched dispatch output — agents reading the
- * contract would never find their data.
+ * `packages/cleo/src/dispatch/engines/session-engine.ts`.
  *
  * @task T963 — contract↔impl drift reconciliation (T910 audit)
  */
 export interface SessionStatusResult {
-  /** True when a session is currently active. @task T963 */
+  /** True when a session is currently active. */
   hasActiveSession: boolean;
-  /**
-   * Active session record (full shape per `Session` contract) or `null`
-   * when none active.
-   * @task T963
-   */
-  session?: SessionOp | null;
-  /**
-   * Current task work state from `meta.focus_state` — tracks the
-   * task the orchestrator is focused on within the session.
-   * @task T963
-   */
+  /** Active session record or `null` when none active. */
+  session?: Session | null;
+  /** Current task work state from `meta.focus_state`. */
   taskWork?: import('../task.js').TaskWorkState | null;
 }
 
 // session.list
+/** Parameters for `session.list`. */
 export interface SessionListParams {
   active?: boolean;
   status?: string;
   limit?: number;
   offset?: number;
 }
+/** Result of `session.list`. */
 export interface SessionListResult {
-  sessions: SessionOp[];
+  sessions: Session[];
   total: number;
   filtered: number;
 }
 
 // session.show
+/** Parameters for `session.show`. */
 export interface SessionShowParams {
   sessionId: string;
+  /** When set to 'debrief', returns debrief data instead of the raw session. */
+  include?: string;
+}
+/**
+ * Result of `session.show`.
+ *
+ * @remarks
+ * `unknown` because `show` with `include='debrief'` returns opaque debrief
+ * data (DebriefData | fallback object) rather than a Session record.
+ */
+export type SessionShowResult = unknown;
+
+// session.find
+/** Parameters for `session.find` — lightweight session discovery. */
+export interface SessionFindParams {
+  status?: string;
+  scope?: string;
+  query?: string;
+  limit?: number;
+}
+/** Result of `session.find` — minimal session records. */
+export interface SessionFindResult {
+  sessions: Array<{
+    id: string;
+    name: string;
+    status: string;
+    startedAt: string;
+    scope: unknown;
+  }>;
+}
+
+// session.decision.log
+/** Parameters for `session.decision.log`. */
+export interface SessionDecisionLogParams {
+  sessionId?: string;
+  taskId?: string;
+}
+/** A single decision record in the audit trail. */
+export interface DecisionRecord {
+  id: string;
+  sessionId: string;
+  taskId: string;
+  decision: string;
+  rationale: string;
+  alternatives?: string[];
+  timestamp: string;
+}
+/** Result of `session.decision.log`. */
+export type SessionDecisionLogResult = DecisionRecord[];
+
+// session.context.drift
+/** Parameters for `session.context.drift`. */
+export interface SessionContextDriftParams {
+  sessionId?: string;
+}
+/** Result of `session.context.drift`. */
+export interface SessionContextDriftResult {
+  score: number;
+  factors: string[];
+  completedInScope: number;
+  totalInScope: number;
+  outOfScope: number;
+}
+
+// session.handoff.show
+/** Parameters for `session.handoff.show`. */
+export interface SessionHandoffShowParams {
+  /**
+   * Scope filter string. Use 'global' for global scope or 'epic:<id>' for
+   * epic-scoped handoff data.
+   */
+  scope?: string;
+}
+/** Result of `session.handoff.show`. */
+export interface SessionHandoffShowResult {
+  sessionId: string;
+  handoff: unknown;
+}
+
+// session.briefing.show
+/** Parameters for `session.briefing.show`. */
+export interface SessionBriefingShowParams {
+  maxNextTasks?: number;
+  maxBugs?: number;
+  maxBlocked?: number;
+  maxEpics?: number;
+  scope?: string;
 }
-export type SessionShowResult = SessionOp;
+/**
+ * Result of `session.briefing.show` — composite session-start context.
+ * The full shape is defined in `@cleocode/core/internal.SessionBriefing`.
+ */
+export type SessionBriefingShowResult = unknown;
 
-// session.history
+// session.history (query — not in primary handler but exported for completeness)
+/** Parameters for `session.history`. */
 export interface SessionHistoryParams {
   limit?: number;
 }
+/** A single session history entry. */
 export interface SessionHistoryEntry {
   sessionId: string;
   name: string;
@@ -89,24 +184,41 @@ export interface SessionHistoryEntry {
   tasksCompleted: number;
   duration: string;
 }
+/** Result of `session.history`. */
 export type SessionHistoryResult = SessionHistoryEntry[];
 
-/**
- * Mutate Operations
- */
+// ---------------------------------------------------------------------------
+// Mutate Operations
+// ---------------------------------------------------------------------------
 
 // session.start
+/** Parameters for `session.start`. */
 export interface SessionStartParams {
   scope: string;
   name?: string;
   autoStart?: boolean;
   startTask?: string;
+  /** Alias for startTask — accepted from CLI for backward compat. */
+  focus?: string;
+  /** Enable full query+mutation audit logging for behavioral grading. */
+  grade?: boolean;
+  /**
+   * HMAC-SHA256 owner-auth token for L4a override authentication (T1118).
+   *
+   * Derived from HMAC-SHA256(key=password, data=sessionId) during
+   * `cleo session start --owner-auth`. Stored in sessions.owner_auth_token
+   * and validated on every `CLEO_OWNER_OVERRIDE` call.
+   */
+  ownerAuthToken?: string;
 }
-export type SessionStartResult = SessionOp;
+/** Result of `session.start` — the newly created session. */
+export type SessionStartResult = Session;
 
 // session.end
+/** Parameters for `session.end`. */
 export interface SessionEndParams {
-  notes?: string;
+  note?: string;
+  nextAction?: string;
   /**
    * Structured session summary for direct ingestion into brain.db.
    * When provided, CLEO persists key learnings, decisions, patterns, and next actions.
@@ -114,13 +226,10 @@ export interface SessionEndParams {
    */
   sessionSummary?: import('../config.js').SessionSummaryInput;
 }
+/** Result of `session.end`. */
 export interface SessionEndResult {
-  session: SessionOp;
-  summary: {
-    duration: string;
-    tasksCompleted: number;
-    tasksCreated: number;
-  };
+  sessionId: string;
+  ended: boolean;
   /**
    * A summarization prompt built from this session's debrief data.
    * Populated when `brain.summarization.enabled` is true.
@@ -130,25 +239,93 @@ export interface SessionEndResult {
 }
 
 // session.resume
+/** Parameters for `session.resume`. */
 export interface SessionResumeParams {
   sessionId: string;
 }
-export type SessionResumeResult = SessionOp;
+/** Result of `session.resume` — the resumed session. */
+export type SessionResumeResult = Session;
 
 // session.suspend
+/** Parameters for `session.suspend`. */
 export interface SessionSuspendParams {
-  notes?: string;
-}
-export interface SessionSuspendResult {
   sessionId: string;
-  suspended: string;
+  reason?: string;
 }
+/** Result of `session.suspend` — the suspended session. */
+export type SessionSuspendResult = Session;
 
 // session.gc
+/** Parameters for `session.gc`. */
 export interface SessionGcParams {
-  olderThan?: string;
+  maxAgeDays?: number;
 }
+/** Result of `session.gc`. */
 export interface SessionGcResult {
-  cleaned: number;
-  sessionIds: string[];
+  orphaned: string[];
+  removed: string[];
+}
+
+// session.record.decision
+/** Parameters for `session.record.decision`. */
+export interface SessionRecordDecisionParams {
+  sessionId?: string;
+  taskId: string;
+  decision: string;
+  rationale: string;
+  alternatives?: string[];
+}
+/** Result of `session.record.decision`. */
+export type SessionRecordDecisionResult = DecisionRecord;
+
+// session.record.assumption
+/** Parameters for `session.record.assumption`. */
+export interface SessionRecordAssumptionParams {
+  sessionId?: string;
+  taskId?: string;
+  assumption: string;
+  confidence: 'high' | 'medium' | 'low';
+}
+/** Result of `session.record.assumption`. */
+export interface SessionRecordAssumptionResult {
+  id: string;
+  sessionId: string;
+  taskId: string | null;
+  assumption: string;
+  confidence: string;
+  timestamp: string;
 }
+
+// ---------------------------------------------------------------------------
+// Typed operation record (Wave D adapter — T975)
+// ---------------------------------------------------------------------------
+
+/**
+ * Typed operation record for the session domain.
+ *
+ * Maps each operation name (as dispatched by the registry — no domain prefix)
+ * to its `[Params, Result]` tuple. Used by `TypedDomainHandler<SessionOps>`
+ * in the dispatch layer to provide compile-time narrowing of params.
+ *
+ * @task T975 — Wave D typed-dispatch migration
+ */
+export type SessionOps = {
+  readonly status: readonly [SessionStatusParams, SessionStatusResult];
+  readonly list: readonly [SessionListParams, SessionListResult];
+  readonly show: readonly [SessionShowParams, SessionShowResult];
+  readonly find: readonly [SessionFindParams, SessionFindResult];
+  readonly 'decision.log': readonly [SessionDecisionLogParams, SessionDecisionLogResult];
+  readonly 'context.drift': readonly [SessionContextDriftParams, SessionContextDriftResult];
+  readonly 'handoff.show': readonly [SessionHandoffShowParams, SessionHandoffShowResult | null];
+  readonly 'briefing.show': readonly [SessionBriefingShowParams, SessionBriefingShowResult];
+  readonly start: readonly [SessionStartParams, SessionStartResult];
+  readonly end: readonly [SessionEndParams, SessionEndResult];
+  readonly resume: readonly [SessionResumeParams, SessionResumeResult];
+  readonly suspend: readonly [SessionSuspendParams, SessionSuspendResult];
+  readonly gc: readonly [SessionGcParams, SessionGcResult];
+  readonly 'record.decision': readonly [SessionRecordDecisionParams, SessionRecordDecisionResult];
+  readonly 'record.assumption': readonly [
+    SessionRecordAssumptionParams,
+    SessionRecordAssumptionResult,
+  ];
+};

package/src/operations/sticky.ts

@@ -0,0 +1,308 @@
+/**
+ * Sticky Domain Operations Contract (6 operations)
+ *
+ * Query operations: 2
+ * Mutate operations: 4
+ *
+ * Sticky notes are ephemeral task fragments stored in a project-local SQLite database.
+ * They support filtering by status (active/converted/archived), color, priority, and tags.
+ * CLI identifiers start with `sticky.*` and are routed through the `sticky` domain handler.
+ *
+ * SYNC: Canonical type definitions live in packages/core/src/sticky/types.ts.
+ * These operation types are the API contract (wire format).
+ *
+ * @task T1031 — Contract authoring for T980 migration worker
+ * @see packages/cleo/src/dispatch/domains/sticky.ts
+ * @see packages/core/src/sticky/types.ts
+ */
+
+/**
+ * Sticky note status classification.
+ */
+export type StickyNoteStatus = 'active' | 'converted' | 'archived';
+
+/**
+ * Sticky note color options.
+ */
+export type StickyNoteColor = 'yellow' | 'blue' | 'green' | 'red' | 'purple';
+
+/**
+ * Sticky note priority levels.
+ */
+export type StickyNotePriority = 'low' | 'medium' | 'high';
+
+/**
+ * Converted target type for note transformation.
+ */
+export type StickyConvertTargetType = 'task' | 'memory' | 'session_note' | 'task_note';
+
+/**
+ * Reference to a converted target (task, memory, session note, or task note).
+ */
+export interface StickyConvertedTarget {
+  /** Type of the conversion target. */
+  type: StickyConvertTargetType;
+  /** ID of the target item. */
+  id: string;
+}
+
+/**
+ * Core sticky note wire format (API projection).
+ *
+ * Returned by list, show, add, archive, purge operations.
+ */
+export interface StickyNoteOp {
+  /** Unique ID (SN-001, SN-002...). */
+  id: string;
+  /** Raw note text content. */
+  content: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+  /** ISO 8601 last update timestamp. */
+  updatedAt?: string;
+  /** Array of user-assigned tags. */
+  tags: string[];
+  /** Current status (active/converted/archived). */
+  status: StickyNoteStatus;
+  /** Conversion target if converted (nullable). */
+  convertedTo?: StickyConvertedTarget;
+  /** Visual color indicator. */
+  color?: StickyNoteColor;
+  /** Priority level. */
+  priority?: StickyNotePriority;
+  /** Source type for BRAIN queries. */
+  sourceType: string;
+}
+
+/**
+ * List of sticky notes with pagination metadata.
+ */
+export interface StickyListData {
+  /** Array of sticky notes matching the filter. */
+  stickies: StickyNoteOp[];
+  /** Total count of stickies in the project (ignoring pagination). */
+  total: number;
+  /** Count of stickies that matched the filter. */
+  filtered: number;
+}
+
+// ============================================================================
+// Query Operations
+// ============================================================================
+
+// --------------------------------------------------------------------------
+// sticky.list
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `sticky.list`.
+ *
+ * @remarks
+ * All filter parameters are optional and combine with AND logic (all must match).
+ * Pagination applies to filtered results.
+ */
+export interface StickyListParams {
+  /** Filter to notes with a specific status. */
+  status?: StickyNoteStatus;
+  /** Filter to notes with a specific color. */
+  color?: StickyNoteColor;
+  /** Filter to notes with a specific priority. */
+  priority?: StickyNotePriority;
+  /** Filter to notes containing ALL of the specified tags. */
+  tags?: string[];
+  /** Max results to return (pagination limit). */
+  limit?: number;
+  /** Pagination offset (number of results to skip). */
+  offset?: number;
+}
+
+/**
+ * Result of `sticky.list`.
+ *
+ * @remarks
+ * Returns a paginated list of sticky notes with total and filtered counts.
+ */
+export interface StickyListResult {
+  /** Array of sticky notes for this page. */
+  stickies: StickyNoteOp[];
+  /** Total sticky note count across all filters. */
+  total: number;
+  /** Count of stickies matching the applied filters. */
+  filtered: number;
+}
+
+// --------------------------------------------------------------------------
+// sticky.show
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `sticky.show`.
+ */
+export interface StickyShowParams {
+  /** Sticky note ID to retrieve (required). */
+  stickyId: string;
+}
+
+/**
+ * Result of `sticky.show`.
+ *
+ * @remarks
+ * Returns the full sticky note record, or error if not found.
+ */
+export type StickyShowResult = StickyNoteOp;
+
+// ============================================================================
+// Mutate Operations
+// ============================================================================
+
+// --------------------------------------------------------------------------
+// sticky.add
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `sticky.add`.
+ */
+export interface StickyAddParams {
+  /** Note text content (required). */
+  content: string;
+  /** User-assigned tags. */
+  tags?: string[];
+  /** Visual color indicator. */
+  color?: StickyNoteColor;
+  /** Priority level. */
+  priority?: StickyNotePriority;
+}
+
+/**
+ * Result of `sticky.add`.
+ *
+ * @remarks
+ * Returns the newly-created sticky note record.
+ */
+export type StickyAddResult = StickyNoteOp;
+
+// --------------------------------------------------------------------------
+// sticky.convert
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `sticky.convert`.
+ *
+ * @remarks
+ * Converts a sticky note to a different item type (task, memory, session note, task note).
+ * Required params vary by targetType:
+ *   - task: optional title
+ *   - memory: optional memoryType
+ *   - session_note: optional sessionId
+ *   - task_note: required taskId
+ */
+export interface StickyConvertParams {
+  /** Sticky note ID to convert (required). */
+  stickyId: string;
+  /** Target item type: task, memory, session_note, or task_note (required). */
+  targetType: StickyConvertTargetType;
+  /** Optional title when converting to task. */
+  title?: string;
+  /** Optional memory type when converting to memory (observation, decision, pattern, etc.). */
+  memoryType?: string;
+  /** Required task ID when converting to task_note. */
+  taskId?: string;
+  /** Optional session ID when converting to session_note. */
+  sessionId?: string;
+}
+
+/**
+ * Result of `sticky.convert`.
+ *
+ * @remarks
+ * Returns the target item ID that was created/updated by the conversion.
+ * The returned key varies by targetType:
+ *   - task → taskId
+ *   - memory → memoryId
+ *   - session_note → sessionId
+ *   - task_note → taskId
+ */
+export interface StickyConvertResult {
+  /** ID of the created or updated target item (key name varies by type). */
+  taskId?: string;
+  memoryId?: string;
+  sessionId?: string;
+}
+
+// --------------------------------------------------------------------------
+// sticky.archive
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `sticky.archive`.
+ */
+export interface StickyArchiveParams {
+  /** Sticky note ID to archive (required). */
+  stickyId: string;
+}
+
+/**
+ * Result of `sticky.archive`.
+ *
+ * @remarks
+ * Returns the archived sticky note record with status updated to 'archived'.
+ */
+export type StickyArchiveResult = StickyNoteOp;
+
+// --------------------------------------------------------------------------
+// sticky.purge
+// --------------------------------------------------------------------------
+
+/**
+ * Parameters for `sticky.purge`.
+ */
+export interface StickyPurgeParams {
+  /** Sticky note ID to permanently delete (required). */
+  stickyId: string;
+}
+
+/**
+ * Result of `sticky.purge`.
+ *
+ * @remarks
+ * Returns the purged sticky note record. After purge, the note is permanently deleted
+ * from the database and cannot be recovered.
+ */
+export type StickyPurgeResult = StickyNoteOp;
+
+// ============================================================================
+// Discriminated Union Types
+// ============================================================================
+
+/**
+ * All sticky operation keys (for TypedDomainHandler routing).
+ */
+export type StickyOpKey =
+  | 'sticky.list'
+  | 'sticky.show'
+  | 'sticky.add'
+  | 'sticky.convert'
+  | 'sticky.archive'
+  | 'sticky.purge';
+
+/**
+ * Sticky operations discriminated union.
+ *
+ * @remarks
+ * Each variant carries:
+ * - `op`: the operation key (for routing)
+ * - `params`: strongly-typed parameters for this operation
+ * - `result`: strongly-typed return type for this operation
+ *
+ * Consumed by packages/cleo/src/dispatch/domains/sticky.ts via TypedDomainHandler<StickyOps>.
+ *
+ * @task T1031
+ * @task T980 — migration worker that consumes this contract
+ */
+export type StickyOps =
+  | { op: 'sticky.list'; params: StickyListParams; result: StickyListResult }
+  | { op: 'sticky.show'; params: StickyShowParams; result: StickyShowResult }
+  | { op: 'sticky.add'; params: StickyAddParams; result: StickyAddResult }
+  | { op: 'sticky.convert'; params: StickyConvertParams; result: StickyConvertResult }
+  | { op: 'sticky.archive'; params: StickyArchiveParams; result: StickyArchiveResult }
+  | { op: 'sticky.purge'; params: StickyPurgeParams; result: StickyPurgeResult };