@cleocode/contracts 2026.4.116 → 2026.4.121

package/dist/operations/nexus-user-profile.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Wire-format contracts for the NEXUS user_profile SDK operations.
+ *
+ * These types describe the parameter and result shapes for the five
+ * user-profile SDK functions shipped in T1078 (PSYCHE Wave 1).  They follow
+ * the same contract pattern as the rest of @cleocode/contracts/operations/.
+ *
+ * Operations:
+ *   nexus.profile.view       — query  — list all traits (with optional confidence filter)
+ *   nexus.profile.get        — query  — fetch a single trait by key
+ *   nexus.profile.import     — mutate — import from user_profile.json
+ *   nexus.profile.export     — mutate — export to user_profile.json
+ *   nexus.profile.reinforce  — mutate — increment reinforcement for a trait
+ *   nexus.profile.upsert     — mutate — create-or-update a single trait
+ *   nexus.profile.supersede  — mutate — mark one trait as superseded by another
+ *
+ * @task T1078
+ * @task T1079
+ * @task T1080
+ * @epic T1076
+ */
+/**
+ * A single user-profile trait record.
+ *
+ * This is the canonical in-memory / wire shape for all profile operations.
+ * The corresponding SQLite row type is `UserProfileRow` in
+ * `packages/core/src/store/nexus-schema.ts`.
+ */
+export interface UserProfileTrait {
+    /** Stable semantic key, e.g. "prefers-zero-deps" or "verbose-git-logs". */
+    traitKey: string;
+    /** JSON-encoded value (string, number, boolean, or serialised object). */
+    traitValue: string;
+    /** Bayesian confidence in [0.0, 1.0]. */
+    confidence: number;
+    /**
+     * Origin of this observation.  Convention:
+     *   "dialectic:<sessionId>"    — derived by the Dialectic Evaluator (Wave 3)
+     *   "import:user_profile.json" — loaded from a portable profile export
+     *   "manual"                   — set directly via CLI reinforce command
+     */
+    source: string;
+    /**
+     * Soft FK to a future session_messages.id.
+     * Null until Wave 5 (T1145) ships the session_messages table.
+     */
+    derivedFromMessageId: string | null;
+    /** ISO 8601 string when the trait was first observed. */
+    firstObservedAt: string;
+    /** ISO 8601 string of the most recent reinforcement event. */
+    lastReinforcedAt: string;
+    /** Number of times this trait has been confirmed (starts at 1). */
+    reinforcementCount: number;
+    /**
+     * traitKey of the superseding trait, or null if still active.
+     * Set by `supersedeTrait` (T1139 supersession graph prep).
+     */
+    supersededBy: string | null;
+}
+/** Parameters for `nexus.profile.view`. */
+export interface NexusProfileViewParams {
+    /** Only return traits with confidence >= this value. Default: 0.0 (all). */
+    minConfidence?: number;
+}
+/** Result of `nexus.profile.view`. */
+export interface NexusProfileViewResult {
+    /** All matching traits, ordered by confidence desc, then traitKey asc. */
+    traits: UserProfileTrait[];
+    /** Total count of traits returned. */
+    count: number;
+}
+/** Parameters for `nexus.profile.get`. */
+export interface NexusProfileGetParams {
+    /** Trait key to retrieve (required). */
+    traitKey: string;
+}
+/** Result of `nexus.profile.get`. */
+export interface NexusProfileGetResult {
+    /** The trait, or null when not found. */
+    trait: UserProfileTrait | null;
+}
+/** Parameters for `nexus.profile.import`. */
+export interface NexusProfileImportParams {
+    /**
+     * Absolute path to the JSON file to import.
+     * Defaults to `~/.cleo/user_profile.json` when omitted.
+     */
+    path?: string;
+}
+/** Result of `nexus.profile.import`. */
+export interface NexusProfileImportResult {
+    /** Number of traits successfully upserted. */
+    imported: number;
+    /** Number of traits skipped due to conflict resolution (lower confidence). */
+    skipped: number;
+    /** Number of traits where the incoming entry superseded the existing one. */
+    superseded: number;
+}
+/** Parameters for `nexus.profile.export`. */
+export interface NexusProfileExportParams {
+    /**
+     * Absolute path for the output JSON file.
+     * Defaults to `~/.cleo/user_profile.json` when omitted.
+     */
+    path?: string;
+}
+/** Result of `nexus.profile.export`. */
+export interface NexusProfileExportResult {
+    /** Absolute path the file was written to. */
+    path: string;
+    /** Number of traits written. */
+    count: number;
+}
+/** Parameters for `nexus.profile.reinforce`. */
+export interface NexusProfileReinforceParams {
+    /** Key of the trait to reinforce (required). */
+    traitKey: string;
+    /**
+     * Source identifier for this reinforcement event.
+     * Defaults to "manual" when called from the CLI.
+     */
+    source?: string;
+}
+/** Result of `nexus.profile.reinforce`. */
+export interface NexusProfileReinforceResult {
+    /** New reinforcement count after this event. */
+    reinforcementCount: number;
+    /** Updated confidence after this event. */
+    confidence: number;
+}
+/** Parameters for `nexus.profile.upsert`. */
+export interface NexusProfileUpsertParams {
+    /** Trait to create or update (required). */
+    trait: Pick<UserProfileTrait, 'traitKey' | 'traitValue' | 'confidence' | 'source' | 'derivedFromMessageId'>;
+}
+/** Result of `nexus.profile.upsert`. */
+export interface NexusProfileUpsertResult {
+    /** Whether a new row was created (true) or an existing row was updated (false). */
+    created: boolean;
+}
+/** Parameters for `nexus.profile.supersede`. */
+export interface NexusProfileSupersedeParams {
+    /** The trait key that is being deprecated. */
+    oldKey: string;
+    /** The trait key that replaces it. */
+    newKey: string;
+}
+/** Result of `nexus.profile.supersede`. */
+export interface NexusProfileSupersedeResult {
+    /** Old trait key (now has supersededBy set). */
+    oldKey: string;
+    /** New trait key (the superseding trait). */
+    newKey: string;
+}
+//# sourceMappingURL=nexus-user-profile.d.ts.map

package/dist/operations/nexus-user-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-user-profile.d.ts","sourceRoot":"","sources":["../../src/operations/nexus-user-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAMD,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,sCAAsC;IACtC,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,qCAAqC;AACrC,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAChC;AAMD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wCAAwC;AACxC,MAAM,WAAW,wBAAwB;IACvC,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wCAAwC;AACxC,MAAM,WAAW,wBAAwB;IACvC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,gDAAgD;AAChD,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2CAA2C;AAC3C,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,KAAK,EAAE,IAAI,CACT,gBAAgB,EAChB,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,sBAAsB,CAC7E,CAAC;CACH;AAED,wCAAwC;AACxC,MAAM,WAAW,wBAAwB;IACvC,mFAAmF;IACnF,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,gDAAgD;AAChD,MAAM,WAAW,2BAA2B;IAC1C,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,2BAA2B;IAC1C,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/operations/nexus-user-profile.js

@@ -0,0 +1,23 @@
+/**
+ * Wire-format contracts for the NEXUS user_profile SDK operations.
+ *
+ * These types describe the parameter and result shapes for the five
+ * user-profile SDK functions shipped in T1078 (PSYCHE Wave 1).  They follow
+ * the same contract pattern as the rest of @cleocode/contracts/operations/.
+ *
+ * Operations:
+ *   nexus.profile.view       — query  — list all traits (with optional confidence filter)
+ *   nexus.profile.get        — query  — fetch a single trait by key
+ *   nexus.profile.import     — mutate — import from user_profile.json
+ *   nexus.profile.export     — mutate — export to user_profile.json
+ *   nexus.profile.reinforce  — mutate — increment reinforcement for a trait
+ *   nexus.profile.upsert     — mutate — create-or-update a single trait
+ *   nexus.profile.supersede  — mutate — mark one trait as superseded by another
+ *
+ * @task T1078
+ * @task T1079
+ * @task T1080
+ * @epic T1076
+ */
+export {};
+//# sourceMappingURL=nexus-user-profile.js.map

package/dist/operations/nexus-user-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexus-user-profile.js","sourceRoot":"","sources":["../../src/operations/nexus-user-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/operations/worktree.d.ts

@@ -1,7 +1,7 @@
 /**
  * Worktree backend SDK operation types (T1161).
  *
- * Wire-format types for the `@cleocode/worktree-backend` SDK surface.
+ * Wire-format types for the `@cleocode/worktree` SDK surface.
  * Defines the contract for createWorktree, destroyWorktree, listWorktrees,
  * and pruneWorktrees operations with XDG path canon (D029) and declarative
  * hooks (D030 native lift of worktrunk missing features).

package/dist/operations/worktree.js

@@ -1,7 +1,7 @@
 /**
  * Worktree backend SDK operation types (T1161).
  *
- * Wire-format types for the `@cleocode/worktree-backend` SDK surface.
+ * Wire-format types for the `@cleocode/worktree` SDK surface.
  * Defines the contract for createWorktree, destroyWorktree, listWorktrees,
  * and pruneWorktrees operations with XDG path canon (D029) and declarative
  * hooks (D030 native lift of worktrunk missing features).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.4.116",
+  "version": "2026.4.121",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -435,8 +435,49 @@ export type {
   WikiStateFile,
   WikiSymbolRow,
 } from './nexus-wiki-ops.js';
+// Dialectic Evaluator operation types (T1087 Wave 3)
+export type {
+  ApplyInsightsParams,
+  ApplyInsightsResult,
+  DialecticInsights,
+  DialecticTurn,
+  EvaluateDialecticParams,
+  EvaluateDialecticResult,
+} from './operations/dialectic.js';
 // === Operations Types (API wire format, namespaced to avoid collision with domain types) ===
 export * as ops from './operations/index.js';
+// Multi-pass retrieval bundle types (PSYCHE Wave 4 · T1090)
+export type {
+  PassMask,
+  RetrievalActiveTask,
+  RetrievalBundle,
+  RetrievalDecision,
+  RetrievalLearning,
+  RetrievalObservation,
+  RetrievalPattern,
+  RetrievalRequest,
+  RetrievalTokenCounts,
+} from './operations/memory.js';
+// === NEXUS User Profile Types (T1076 PSYCHE Wave 1) ===
+// Re-exported at top level so @cleocode/core/nexus and CLI dispatch can
+// import without the `ops.` namespace hop.
+export type {
+  NexusProfileExportParams,
+  NexusProfileExportResult,
+  NexusProfileGetParams,
+  NexusProfileGetResult,
+  NexusProfileImportParams,
+  NexusProfileImportResult,
+  NexusProfileReinforceParams,
+  NexusProfileReinforceResult,
+  NexusProfileSupersedeParams,
+  NexusProfileSupersedeResult,
+  NexusProfileUpsertParams,
+  NexusProfileUpsertResult,
+  NexusProfileViewParams,
+  NexusProfileViewResult,
+  UserProfileTrait,
+} from './operations/nexus-user-profile.js';
 // Commonly used ops types re-exported at top level for convenience
 export type { BrainState } from './operations/orchestrate.js';
 // ParamDef contract — re-exported at top level (SSoT for all operation param descriptors)
@@ -494,7 +535,7 @@ export type {
   VariableResolver,
 } from './operations/variable-substitution.js';
 // === Worktree Backend SDK Types (T1161) ===
-// Re-exported at top level so @cleocode/worktree-backend and callers can
+// Re-exported at top level so @cleocode/worktree and callers can
 // import without the `ops.` namespace hop.
 export type {
   CreateWorktreeOptions,

package/src/operations/dialectic.ts

@@ -0,0 +1,167 @@
+/**
+ * Wire-format contracts for the Dialectic Evaluator SDK operations.
+ *
+ * Exported types describe the parameter and result shapes for the
+ * two primary dialectic evaluation functions shipped in T1087 (PSYCHE Wave 3).
+ * They follow the same contract pattern as the rest of @cleocode/contracts/operations/.
+ *
+ * Operations:
+ *   evaluateDialectic — analyse a single user↔system turn and extract insights
+ *   applyInsights     — persist extracted insights to nexus.db and brain.db
+ *
+ * Design constraints (ADR-055 / D028 boundary rules):
+ *  - Lives in `packages/contracts/` — ZERO runtime dependencies.
+ *  - Consumed by `packages/core/src/memory/dialectic-evaluator.ts` and the CQRS
+ *    dispatcher hook in `packages/cleo/src/dispatch/dispatcher.ts`.
+ *  - No cross-package relative imports.
+ *
+ * @task T1087
+ * @task T1088
+ * @epic T1082
+ */
+
+// ============================================================================
+// Core domain types
+// ============================================================================
+
+/**
+ * A single conversational turn passed to the Dialectic Evaluator.
+ *
+ * Represents one exchange between a user and the system.  Both sides are
+ * required so the evaluator can reason about what was asked, what the system
+ * inferred, and whether any behavioural traits or session-level insights can
+ * be extracted.
+ *
+ * @example
+ * ```ts
+ * const turn: DialecticTurn = {
+ *   userMessage:    "always reuse existing helpers before creating new ones",
+ *   systemResponse: "understood — I found `buildRetrievalBundle` which covers your case.",
+ *   activePeerId:   "cleo-prime",
+ *   sessionId:      "ses_20260422131135_5149eb",
+ * };
+ * ```
+ */
+export interface DialecticTurn {
+  /** Raw text of the user's message in this turn. */
+  userMessage: string;
+  /** Raw text of the system's response in this turn. */
+  systemResponse: string;
+  /**
+   * The CANT agent peer ID that is active for this turn.
+   * Matches `PeerIdentity.peerId` from `packages/contracts/src/peer.ts`.
+   * Defaults to `"global"` when no peer context is available.
+   */
+  activePeerId: string;
+  /** Session ID from the CLEO session store (e.g. `ses_20260422131135_5149eb`). */
+  sessionId: string;
+}
+
+/**
+ * Structured insights extracted from a single dialectic turn.
+ *
+ * The Dialectic Evaluator populates this after analysing a conversational turn.
+ * It is then consumed by `applyInsights` to route each sub-array to the
+ * correct storage backend.
+ *
+ * Routing summary:
+ *  - `globalTraits`     → `upsertUserProfileTrait` (nexus.db user_profile table)
+ *  - `peerInsights`     → `observeBrain` with `peerId` set + source `"dialectic:<sessionId>"`
+ *  - `sessionNarrativeDelta` → `appendNarrativeDelta` in session-narrative.ts
+ */
+export interface DialecticInsights {
+  /**
+   * User-level behavioural traits extracted from the turn.
+   *
+   * These are global, session-independent facts about the user — e.g.
+   * "prefers-zero-deps", "verbose-git-logs".  Persisted to the user_profile
+   * table in nexus.db via `upsertUserProfileTrait` (Wave 1).
+   */
+  globalTraits: Array<{
+    /** Stable semantic key for the trait (kebab-case). */
+    key: string;
+    /** JSON-serialisable value string. */
+    value: string;
+    /** Bayesian confidence in [0.0, 1.0]. */
+    confidence: number;
+  }>;
+
+  /**
+   * Peer-scoped insights relevant only to the active CANT agent.
+   *
+   * Persisted to brain.db via `observeBrain` with the `peerId` field set
+   * to the originating peer and `sourceType` set to `"dialectic"`.
+   */
+  peerInsights: Array<{
+    /** Observation key or short title. */
+    key: string;
+    /** Observation detail text (max ~300 chars). */
+    value: string;
+    /** Peer the insight belongs to (copied from `DialecticTurn.activePeerId`). */
+    peerId: string;
+    /** Bayesian confidence in [0.0, 1.0]. */
+    confidence: number;
+  }>;
+
+  /**
+   * Short narrative description of what happened in this turn.
+   *
+   * Appended to the rolling `session_narrative` table via `appendNarrativeDelta`.
+   * Omit (or leave undefined) when the turn has no meaningful narrative content
+   * (e.g. short ack messages).
+   *
+   * Max length: 500 chars.
+   */
+  sessionNarrativeDelta?: string;
+}
+
+// ============================================================================
+// Params / Result types (for registry-driven dispatch surface)
+// ============================================================================
+
+/**
+ * Parameters for the `evaluateDialectic` SDK function.
+ *
+ * Wraps `DialecticTurn` in the standard params envelope so that the operation
+ * can be registered in the dispatch registry if needed in the future.
+ */
+export interface EvaluateDialecticParams {
+  /** The conversational turn to evaluate. */
+  turn: DialecticTurn;
+}
+
+/**
+ * Result returned by `evaluateDialectic`.
+ *
+ * Contains the extracted insights ready for downstream persistence.
+ */
+export interface EvaluateDialecticResult {
+  /** Extracted insights from the evaluated turn. */
+  insights: DialecticInsights;
+  /** Name of the LLM backend that was used, or `"stub"` when no backend was available. */
+  backend: 'anthropic' | 'ollama' | 'transformers' | 'stub';
+}
+
+/**
+ * Parameters for the `applyInsights` SDK function.
+ */
+export interface ApplyInsightsParams {
+  /** Insights to persist (produced by `evaluateDialectic`). */
+  insights: DialecticInsights;
+  /** Session ID used to build the `dialectic:<sessionId>` source tag. */
+  sessionId: string;
+  /** The CANT agent peer ID that produced these insights. */
+  activePeerId: string;
+}
+
+/**
+ * Result returned by `applyInsights`.
+ */
+export interface ApplyInsightsResult {
+  /** Number of global traits upserted to nexus.db user_profile. */
+  globalTraitsApplied: number;
+  /** Number of peer insights stored to brain.db. */
+  peerInsightsApplied: number;
+  /** Whether a session narrative entry was written. */
+  narrativeDeltaApplied: boolean;
+}

package/src/operations/index.ts

@@ -11,6 +11,7 @@ export * from './issues.js';
 export * from './lifecycle.js';
 export * from './memory.js';
 export * from './nexus.js';
+export * from './nexus-user-profile.js';
 export * from './orchestrate.js';
 export * from './params.js';
 export * from './release.js';

package/src/operations/memory.ts

@@ -1038,6 +1038,186 @@ export interface MemoryPromoteExplainResult {
   scoreBreakdown: MemoryPromoteScoreBreakdown;
 }
 
+// ============================================================================
+// Multi-Pass Retrieval Bundle (PSYCHE Wave 4 · T1090)
+// ============================================================================
+
+/**
+ * Controls which passes are executed in `buildRetrievalBundle`.
+ *
+ * When all fields are `true` (the default), all three passes run in parallel.
+ * Set individual passes to `false` to skip them for token-budget optimisation.
+ */
+export interface PassMask {
+  /** Cold pass: user-profile traits + peer instructions from NEXUS. */
+  cold: boolean;
+  /** Warm pass: peer-scoped learnings, patterns, and decisions from BRAIN. */
+  warm: boolean;
+  /** Hot pass: session narrative + recent observations + active tasks. */
+  hot: boolean;
+}
+
+/**
+ * Input to `buildRetrievalBundle`.
+ *
+ * All four fields are required; pass an empty string for `query` when no
+ * user-provided search term is available.
+ */
+export interface RetrievalRequest {
+  /** CANT peer identifier, e.g. `"cleo-prime"` or `"global"`. */
+  peerId: string;
+  /** Active session identifier. */
+  sessionId: string;
+  /** Optional user-query used to scope warm-pass memory search. */
+  query?: string;
+  /**
+   * Which passes to execute.  Defaults to `{ cold: true, warm: true, hot: true }`.
+   */
+  passMask?: PassMask;
+  /**
+   * Token budget for the bundle (default: 4000).
+   * Split 20 / 50 / 30 across cold / warm / hot.
+   * When total exceeds budget, hot pass is trimmed first.
+   */
+  tokenBudget?: number;
+}
+
+/**
+ * Compact task record returned by the hot pass.
+ *
+ * A narrow projection of the full `Task` type — only the fields needed for
+ * briefing context are included to keep token cost low.
+ */
+export interface RetrievalActiveTask {
+  /** Task identifier (e.g. `"T1090"`). */
+  id: string;
+  /** Task title. */
+  title: string;
+  /** Current lifecycle status. */
+  status: string;
+}
+
+/**
+ * Compact observation record returned by the hot pass.
+ *
+ * A narrow projection of a `brain_observations` row — only the display fields.
+ */
+export interface RetrievalObservation {
+  /** Observation identifier (e.g. `"O-abc123"`). */
+  id: string;
+  /** Short display title. */
+  title: string;
+  /** Full narrative text. */
+  narrative: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+}
+
+/**
+ * Compact learning record returned by the warm pass.
+ */
+export interface RetrievalLearning {
+  /** Learning identifier (e.g. `"L-def456"`). */
+  id: string;
+  /** Insight text. */
+  insight: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+}
+
+/**
+ * Compact pattern record returned by the warm pass.
+ */
+export interface RetrievalPattern {
+  /** Pattern identifier (e.g. `"P-ghi789"`). */
+  id: string;
+  /** Pattern text. */
+  pattern: string;
+  /** ISO 8601 extraction timestamp. */
+  extractedAt: string;
+}
+
+/**
+ * Compact decision record returned by the warm pass.
+ */
+export interface RetrievalDecision {
+  /** Decision identifier (e.g. `"D-jkl012"`). */
+  id: string;
+  /** Decision statement. */
+  decision: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+}
+
+/**
+ * Token-budget accounting for the three retrieval passes.
+ */
+export interface RetrievalTokenCounts {
+  /** Estimated tokens consumed by the cold pass. */
+  cold: number;
+  /** Estimated tokens consumed by the warm pass. */
+  warm: number;
+  /** Estimated tokens consumed by the hot pass. */
+  hot: number;
+  /** Sum of cold + warm + hot. */
+  total: number;
+}
+
+/**
+ * Structured context bundle returned by `buildRetrievalBundle`.
+ *
+ * Three passes correspond to three temporal + topical distances:
+ *
+ * - **cold**: stable identity context (user profile + peer instructions)
+ * - **warm**: recent project memory scoped to this peer (learnings, patterns, decisions)
+ * - **hot**: live session state (narrative + recent observations + active tasks)
+ *
+ * @task T1090
+ * @epic T1083
+ */
+export interface RetrievalBundle {
+  /**
+   * Cold pass — identity + stable context.
+   *
+   * `userProfile` contains the user's known preferences and traits at
+   * >= 0.5 confidence.  `peerInstructions` is a brief instruction string
+   * derived from the peer's CANT definition (empty string when unavailable).
+   */
+  cold: {
+    userProfile: import('./nexus-user-profile.js').UserProfileTrait[];
+    peerInstructions: string;
+  };
+
+  /**
+   * Warm pass — peer-scoped project memory.
+   *
+   * All entries are filtered to `peer_id = peerId OR peer_id = 'global'`
+   * so each peer sees its own memory plus the shared global pool.
+   */
+  warm: {
+    peerLearnings: RetrievalLearning[];
+    peerPatterns: RetrievalPattern[];
+    decisions: RetrievalDecision[];
+  };
+
+  /**
+   * Hot pass — live session state.
+   *
+   * `sessionNarrative` is the rolling prose summary from `session_narrative`
+   * (empty string when no narrative has been recorded yet).
+   * `recentObservations` are the last N observations created in this session.
+   * `activeTasks` are tasks with status `active` or `in_progress`.
+   */
+  hot: {
+    sessionNarrative: string;
+    recentObservations: RetrievalObservation[];
+    activeTasks: RetrievalActiveTask[];
+  };
+
+  /** Per-pass and total token-budget accounting. */
+  tokenCounts: RetrievalTokenCounts;
+}
+
 // ============================================================================
 // Paginated result helper (for HTTP list surfaces that opt into LAFSPage)
 // ============================================================================