@cleocode/contracts 2026.5.96 → 2026.5.98

package/src/dispatch/operation-def.ts

@@ -0,0 +1,102 @@
+/**
+ * Dispatch operation-def contracts.
+ *
+ * Canonical home for the {@link OperationDef} and {@link Resolution}
+ * interfaces that describe a single dispatchable CQRS operation and the
+ * result of resolving one from the operation registry.
+ *
+ * Promoted to `@cleocode/contracts` in Phase 0b of the SG-ARCH-SOLID Saga
+ * (T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954). Originally defined in
+ * `packages/cleo/src/dispatch/registry.ts` (lines 14-41 / 43-53). The
+ * `packages/cleo` definition is now a re-export shim — every consumer of
+ * `OperationDef` / `Resolution` continues to compile unchanged.
+ *
+ * This promotion unblocks E-CLI-BOUNDARY (T9833) — the registry data
+ * relocation can now move {@link OPERATIONS} into `@cleocode/contracts`
+ * (or split it without changing the type's canonical home) without
+ * crossing a circular dependency.
+ *
+ * NOT promoted (intentional — different concern):
+ *   - `OPERATIONS: OperationDef[]` — the registry data itself remains in
+ *     `packages/cleo/src/dispatch/registry.ts` and is the subject of the
+ *     follow-up E-CLI-BOUNDARY epic.
+ *   - The helper functions (`resolve`, `validateRequiredParams`,
+ *     `getByDomain`, `getByGateway`, `getByTier`, `getActiveDomains`,
+ *     `getCounts`, `deriveGatewayMatrix`, `getGatewayDomains`) — they
+ *     operate on the data and remain colocated with it.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+
+import type { ParamDef } from '../operations/params.js';
+import type { CanonicalDomain, Gateway, Tier } from './identity.js';
+
+// Re-export the upstream identity types so consumers can pull every
+// dispatch-related shape from a single subpath without having to know
+// which leaf file each type lives in.
+export type { CanonicalDomain, Gateway, ParamDef, Tier };
+
+// ── OperationDef ─────────────────────────────────────────────────────
+
+/**
+ * Definition of a single dispatchable operation.
+ *
+ * Each entry in the operation registry (currently in
+ * `packages/cleo/src/dispatch/registry.ts`'s `OPERATIONS` array)
+ * conforms to this interface. The dispatcher uses these definitions to
+ * (1) route a {@link CanonicalDomain} + operation-name + {@link Gateway}
+ * triple to its handler, (2) validate that all required parameters are
+ * present, and (3) emit dispatch-validation telemetry.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/registry.ts:14-41`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export interface OperationDef {
+  /** The CQRS gateway ('query' or 'mutate'). */
+  gateway: Gateway;
+  /** The canonical domain this operation belongs to. */
+  domain: CanonicalDomain;
+  /** The specific operation name (e.g. 'show', 'skill.list'). */
+  operation: string;
+  /** Brief description of what the operation does. */
+  description: string;
+  /** Agent progressive-disclosure tier (0=basic, 1=memory/check, 2=full). */
+  tier: Tier;
+  /** Whether the operation is safe to retry. */
+  idempotent: boolean;
+  /** Whether this operation requires an active session. */
+  sessionRequired: boolean;
+  /** List of parameter keys that MUST be present in the request. */
+  requiredParams: string[];
+  /**
+   * Fully-described parameter list. Replaces `requiredParams` when populated.
+   * Empty array = "no declared params" (not "no params accepted").
+   * Optional during T4897 migration — defaults to [] when absent.
+   * @see T4897 for progressive migration
+   */
+  params?: ParamDef[];
+}
+
+// ── Resolution ───────────────────────────────────────────────────────
+
+/**
+ * Resolution output for a dispatch request.
+ *
+ * Returned by the `resolve(gateway, domain, operation)` helper in the
+ * operation registry. Bundles the resolved {@link OperationDef} with the
+ * already-typed `domain` + `operation` strings so downstream consumers
+ * don't have to re-narrow them.
+ *
+ * Originally defined in `packages/cleo/src/dispatch/registry.ts:43-53`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9954 (Phase 0b)
+ */
+export interface Resolution {
+  /** The canonical domain. */
+  domain: CanonicalDomain;
+  /** The operation name. */
+  operation: string;
+  /** The definition of the matched operation. */
+  def: OperationDef;
+}

package/src/doctor.ts

@@ -156,6 +156,50 @@ export interface ComprehensiveAuditResult {
   anomalies: WorktreeAnomaly[];
   /** Total anomaly count. Non-zero triggers exit code 2. */
   count: number;
+  /**
+   * `true` when the audit was aborted early due to a width budget overflow
+   * or a timeout. The `anomalies` list reflects only the entries scanned
+   * before the abort — results may be incomplete.
+   */
+  isPartial?: boolean;
+  /**
+   * Machine-readable reason the scan was cut short.
+   * - `'timeout'`: the configured `timeoutMs` was exceeded.
+   * - `'overflow'`: a per-level entry count exceeded `maxEntriesPerLevel`.
+   */
+  partialReason?: 'timeout' | 'overflow';
+}
+
+/**
+ * Result shape returned by the budgeted orphan scanner
+ * ({@link scanWorktreeOrphansBudgeted}).
+ *
+ * Wraps the bare `OrphanEntry[]` from `scanWorktreeOrphans` with optional
+ * partial-result metadata so callers can surface incomplete scans to the
+ * operator without changing the existing `OrphanEntry[]` return type.
+ */
+export interface OrphanScanResult {
+  /** Discovered orphan entries (may be incomplete when `isPartial` is `true`). */
+  orphans: OrphanEntry[];
+  /**
+   * `true` when the scan was aborted before completion due to a budget
+   * overflow or timeout. The `orphans` list reflects only entries found
+   * before the abort.
+   */
+  isPartial: boolean;
+  /**
+   * Machine-readable reason the scan was cut short.
+   * - `'timeout'`: the configured `timeoutMs` was exceeded.
+   * - `'overflow'`: a per-level entry count exceeded `maxEntriesPerLevel`.
+   * `undefined` when `isPartial` is `false`.
+   */
+  partialReason?: 'timeout' | 'overflow';
+  /**
+   * Human-readable warning message produced when the soft-warn threshold
+   * was crossed (entries per level exceeded `softWarnEntriesPerLevel` but
+   * stayed under the hard stop). `undefined` when no warning was triggered.
+   */
+  softWarnMessage?: string;
 }
 
 /**

package/src/enums.ts

@@ -0,0 +1,144 @@
+/**
+ * Canonical task-axis enum constants.
+ *
+ * Single source of truth for the runtime const arrays that back the
+ * task-axis discriminators (kind, scope, severity, size, archive reason,
+ * relation type). Promoted from `packages/core/src/store/tasks-schema.ts`
+ * in Phase 0c of the SG-ARCH-SOLID Saga so that downstream packages can
+ * import the values without pulling in the Drizzle schema runtime.
+ *
+ * `tasks-schema.ts` imports these arrays back for Drizzle's
+ * `text({ enum: ... })` column declarations, which preserves byte-identical
+ * row-type narrowing and produces zero schema DDL change. `tasks-schema.ts`
+ * also re-exports each constant under its original name to preserve the
+ * existing public surface for every internal `import * as schema` consumer.
+ *
+ * The corresponding union types (`TaskKind`, `TaskScope`, `TaskSeverity`,
+ * `TaskSize`, `ArchiveReasonValue`, etc.) already live in their respective
+ * domain modules (`./task.ts`, `./tasks/archive.ts`) and are re-exported
+ * from the package root.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+/**
+ * Task kind axis — describes the intent of the work rather than its
+ * position in the hierarchy. Defaults to `'work'` to preserve semantics
+ * for tasks created before T944.
+ *
+ * Note: the DB column is named `role`; the TypeScript field is `kind`
+ * (T9067 deferral).
+ *
+ * @task T944
+ * @task T9072
+ */
+export const TASK_KINDS = ['work', 'research', 'experiment', 'bug', 'spike', 'release'] as const;
+
+/**
+ * Task scope axis — describes the granularity of the work (project-wide
+ * vs. feature-scoped vs. unit-scoped). Orthogonal to type and kind.
+ *
+ * Backfill mapping from legacy `type` during migration:
+ *   - `type='epic'`    → `scope='project'`
+ *   - `type='task'`    → `scope='feature'` (also used for NULL legacy rows)
+ *   - `type='subtask'` → `scope='unit'`
+ *
+ * @task T944
+ */
+export const TASK_SCOPES = ['project', 'feature', 'unit'] as const;
+
+/**
+ * Task severity axis — applies to ANY task kind (not just `kind='bug'`).
+ *
+ * Enforced by a CHECK constraint:
+ *   `severity IS NULL OR severity IN ('P0','P1','P2','P3')`
+ *
+ * The original T944 constraint coupled severity to `role='bug'`. T9073
+ * widened the constraint so that spikes, incidents, research tasks, and
+ * any other kind can carry a severity level. Priority and severity are
+ * fully orthogonal axes — setting severity does NOT auto-map to priority
+ * (no SEVERITY_MAP on add/update).
+ *
+ * OWNER-WRITE-ONLY (T944 / T9073 / owner mandate): severity is set
+ * through owner-authenticated paths only (signed attestation via
+ * `appendSignedSeverityAttestation`). This prevents a prompt-injection
+ * exploit where a compromised agent could mark a P0 task as P3 to
+ * force-ship.
+ *
+ * @task T944
+ * @task T9073
+ */
+export const TASK_SEVERITIES = ['P0', 'P1', 'P2', 'P3'] as const;
+
+/**
+ * Task size sentinel values matching the DB CHECK constraint on
+ * `tasks.size`. CLEO favors qualitative sizing over time estimates
+ * (see `cleo memory` rule "No time estimates").
+ *
+ * @task T944
+ */
+export const TASK_SIZES = ['small', 'medium', 'large'] as const;
+
+/**
+ * Truth-grade archive reason values enforced by a SQLite CHECK
+ * constraint on `tasks.archive_reason` (see migration
+ * `20260424000000_t1408-archive-reason-enum`).
+ *
+ * Council 2026-04-24 (FINDING #28 + T1407 follow-through) replaced the
+ * legacy unconstrained TEXT column with this 6-value enum. Rows that
+ * pre-dated the migration with non-conforming values (`completed`,
+ * `deleted`, etc.) were normalized to `'completed-unverified'` before
+ * the CHECK was applied, so EVERY existing row satisfies one of these
+ * literals (or is `NULL`).
+ *
+ * Semantics:
+ *   - `verified`             — closure passed all gates with audit-grade evidence.
+ *   - `reconciled`           — closure derived by reconciliation against an
+ *                              external source of truth (e.g. external task tracker).
+ *   - `superseded`           — closure because another task subsumes the work.
+ *   - `shadowed`             — closure because the task was experiment- or
+ *                              proposal-shadowed by a newer plan.
+ *   - `cancelled`            — closure via explicit cancellation
+ *                              (`status='cancelled'`).
+ *   - `completed-unverified` — closure happened but verification was skipped,
+ *                              incomplete, or failed; metrics MUST NOT count
+ *                              these as quality completions without opt-in.
+ *
+ * @task T1408
+ * @epic T1407
+ */
+export const ARCHIVE_REASONS = [
+  'verified',
+  'reconciled',
+  'superseded',
+  'shadowed',
+  'cancelled',
+  'completed-unverified',
+] as const;
+
+/**
+ * Task relation types matching the DB CHECK constraint on
+ * `task_relations.relation_type`.
+ *
+ *   - `related`     — generic non-blocking association
+ *   - `blocks`      — source MUST complete before target can proceed
+ *   - `duplicates`  — source is a duplicate of target (target is canonical)
+ *   - `absorbs`     — source's work was absorbed into target
+ *   - `fixes`       — source fixes target (bug→fix linkage)
+ *   - `extends`     — source extends or refines target
+ *   - `supersedes`  — source replaces target (target is retired)
+ *   - `groups`      — source groups target (Saga→Epic per ADR-073)
+ *
+ * @task T944
+ * @task ADR-073 (`groups` relation for Saga membership)
+ */
+export const TASK_RELATION_TYPES = [
+  'related',
+  'blocks',
+  'duplicates',
+  'absorbs',
+  'fixes',
+  'extends',
+  'supersedes',
+  'groups',
+] as const;

package/src/index.ts

@@ -269,6 +269,11 @@ export type {
   DependencySpec,
 } from './dependency.js';
 export type { AdapterManifest, DetectionPattern } from './discovery.js';
+// === Dispatch Identity Contracts (T9954 — Phase 0b of SG-ARCH-SOLID / E-CONTRACTS-FOUNDATION) ===
+export type { CanonicalDomain, Gateway, Tier } from './dispatch/identity.js';
+export { CANONICAL_DOMAINS } from './dispatch/identity.js';
+// === Dispatch OperationDef + Resolution (T9954 — Phase 0b of SG-ARCH-SOLID / E-CONTRACTS-FOUNDATION) ===
+export type { OperationDef, Resolution } from './dispatch/operation-def.js';
 // === DocsAccessor Contracts (T9063) ===
 export type {
   DocExportFormat,
@@ -294,10 +299,11 @@ export {
   DocKindConfigError,
   DocKindRegistry,
 } from './docs-taxonomy.js';
-// === Doctor: Worktree-Orphan Audit + Prune Types (T9790, T9808) ===
+// === Doctor: Worktree-Orphan Audit + Prune Types (T9790, T9808, T9962) ===
 export type {
   ComprehensiveAuditResult,
   OrphanEntry,
+  OrphanScanResult,
   PruneAuditEntry,
   PruneResult,
   WorktreeAnomaly,
@@ -317,6 +323,15 @@ export {
   engineSuccess,
   unwrap,
 } from './engine-result.js';
+// === Task-Axis Enum Constants (T9955 — promoted from core/store/tasks-schema.ts) ===
+export {
+  ARCHIVE_REASONS,
+  TASK_KINDS,
+  TASK_RELATION_TYPES,
+  TASK_SCOPES,
+  TASK_SEVERITIES,
+  TASK_SIZES,
+} from './enums.js';
 // === Error Utilities ===
 export {
   ClassifierUnregisteredAgentError,
@@ -444,6 +459,8 @@ export {
 } from './graph.js';
 export type { AdapterHookProvider } from './hooks.js';
 export type { AdapterInstallProvider, InstallOptions, InstallResult } from './install.js';
+// === Background Job Status (T9955 — promoted from core/store/tasks-schema.ts) ===
+export type { BackgroundJobStatus } from './jobs.js';
 export type {
   CleoResponse,
   ConformanceReport,
@@ -530,8 +547,37 @@ export type {
 export type { ResolvedCredential } from './llm/resolved-credential.js';
 // === Logger contract (T9766 — centralized from @cleocode/core) ===
 export type { LoggerConfig } from './logger.js';
+// === BRAIN memory wire-shape contracts (T9956 — promoted from @cleocode/core) ===
+export type {
+  BudgetedEntry,
+  BudgetedResult,
+  BudgetedRetrievalOptions,
+} from './memory/budgeted.js';
 // === ContextEngine contract (canonical home — T9304) ===
 export type { CompressedContext, ContextEngine } from './memory/context-engine.js';
+export type {
+  FetchBrainEntriesParams,
+  FetchBrainEntriesResult,
+  FetchedBrainEntry,
+} from './memory/fetch.js';
+export type {
+  BrainObservationSourceType,
+  DocAttachmentObservationPayload,
+  ObserveBrainParams,
+  ObserveBrainResult,
+} from './memory/observe.js';
+export { BRAIN_OBSERVATION_SOURCE_TYPES } from './memory/observe.js';
+export type {
+  BrainCompactHit,
+  SearchBrainCompactParams,
+  SearchBrainCompactResult,
+} from './memory/search.js';
+export type {
+  BrainAnchor,
+  TimelineBrainParams,
+  TimelineBrainResult,
+  TimelineNeighbor,
+} from './memory/timeline.js';
 export type {
   BridgeDecision,
   BridgeLearning,
@@ -1047,6 +1093,7 @@ export type {
   DepGraphIssue,
   DepsTreeEdge,
   DepsTreeNode,
+  TaskShowAttachmentEntry,
   TasksAddBatchParams,
   TasksAddBatchResult,
   TasksAddParams,
@@ -1283,6 +1330,30 @@ export type {
   ProjectType,
   TestFramework,
 } from './project-context.js';
+// === Provenance Graph Unions (T9955 — promoted from core/store/tasks-schema.ts) ===
+// Note: ReleaseChannel/ReleaseKind/ReleaseScheme/ReleaseStatus collide with the
+// existing `./release/channel.js` + `./release/plan.js` + `./task.js` exports
+// (different domains, different value sets). The colliding 4 are re-exported
+// here under `Provenance…`-qualified aliases. The other 12 keep their natural
+// names — they are unique across the package.
+export type {
+  BrainReleaseLinkType,
+  CommitConventionalType,
+  CommitFileChangeType,
+  CommitLinkKind,
+  CommitLinkSource,
+  PrLinkKind,
+  PrLinkSource,
+  PrState,
+  ReleaseArtifactType,
+  ReleaseChangeType,
+  ReleaseChannel as ProvenanceReleaseChannel,
+  ReleaseClassifiedBy,
+  ReleaseImpact,
+  ReleaseKind as ProvenanceReleaseKind,
+  ReleaseScheme as ProvenanceReleaseScheme,
+  ReleaseStatus as ProvenanceReleaseStatus,
+} from './provenance.js';
 export type { AdapterPathProvider } from './provider-paths.js';
 // === Release Channel ===
 export type { ChannelValidationResult, ReleaseChannel } from './release/channel.js';
@@ -1409,6 +1480,13 @@ export type {
   TaskRefPriority,
   TaskSummary,
 } from './results.js';
+// === Scaffold + Diagnostic Result Types (SG-ARCH-SOLID T9831 / E-CONTRACTS-FOUNDATION T9832) ===
+export type {
+  CheckResult,
+  CheckStatus,
+  HookCheckResult,
+  ScaffoldResult,
+} from './scaffold-diagnostics.js';
 // === SDK Tool Contract (Category B harness-agnostic SDK utilities — T1768 / ADR-064) ===
 export type { SdkTool, SdkToolIdentity } from './sdk-tool.js';
 // === Sentient Tier-2 Types (T1008) ===

package/src/jobs.ts

@@ -0,0 +1,45 @@
+/**
+ * Background job contracts.
+ *
+ * Canonical home for the durable-job lifecycle types. Promoted from
+ * `packages/core/src/store/tasks-schema.ts` in Phase 0c of the
+ * SG-ARCH-SOLID Saga so that the cleo dispatch layer
+ * (`@cleocode/cleo/dispatch/lib/background-jobs.ts`) can import the
+ * status union without pulling in the Drizzle schema runtime.
+ *
+ * The `BACKGROUND_JOB_STATUSES` const array remains in `tasks-schema.ts`
+ * because Drizzle's `text({ enum: ... })` column declaration narrows the
+ * runtime row type directly from that `as const` literal. `tasks-schema.ts`
+ * re-exports {@link BackgroundJobStatus} from this module to preserve the
+ * existing public surface.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9955 (Phase 0c)
+ */
+
+/**
+ * Lifecycle status of a durable background job persisted in `tasks.db`.
+ *
+ *   - `pending`   — created but not yet picked up by a worker
+ *   - `running`   — actively executing; emits heartbeats
+ *   - `complete`  — finished successfully (`result` populated, `error` NULL)
+ *   - `failed`    — finished with an error (`error` populated, `result` NULL)
+ *   - `cancelled` — explicitly cancelled by a caller
+ *   - `orphaned`  — was `running` when the process exited; requires human/agent review
+ *
+ * Jobs survive process restart; any row with `status='running'` at startup
+ * is transitioned to `status='orphaned'` so humans/agents can triage them.
+ *
+ * @task T641
+ * @remarks
+ * The values here MUST stay aligned with `BACKGROUND_JOB_STATUSES` in
+ * `tasks-schema.ts`; that const array drives the Drizzle row type. A
+ * compile-time structural assertion in
+ * `packages/contracts/src/__tests__/jobs.test.ts` pins both sides.
+ */
+export type BackgroundJobStatus =
+  | 'pending'
+  | 'running'
+  | 'complete'
+  | 'failed'
+  | 'cancelled'
+  | 'orphaned';

package/src/memory/budgeted.ts

@@ -0,0 +1,75 @@
+/**
+ * Budget-aware BRAIN retrieval wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `retrieveWithBudget` operation — hybrid (FTS5 + vector KNN + graph) BRAIN
+ * search with token-bounded result accounting. Used by the session-briefing
+ * pipeline (`buildRetrievalBundle`) to assemble cross-table context within
+ * a caller-specified token budget.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` (T549
+ * Wave 3-A region, lines 1305-1340) to `@cleocode/contracts` in Phase 0e
+ * of SG-ARCH-SOLID (E-CONTRACTS-FOUNDATION).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+
+// ── BudgetedRetrievalOptions ────────────────────────────────────────
+
+/**
+ * Optional filters for `retrieveWithBudget`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BudgetedRetrievalOptions {
+  /** Filter by cognitive types (semantic / episodic / procedural). */
+  types?: Array<'semantic' | 'episodic' | 'procedural'>;
+  /** Filter by memory tiers (short / medium / long). */
+  tiers?: Array<'short' | 'medium' | 'long'>;
+  /** When true, only return verified entries. Default: false. */
+  verified?: boolean;
+}
+
+// ── BudgetedEntry ───────────────────────────────────────────────────
+
+/**
+ * A single entry returned by `retrieveWithBudget`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BudgetedEntry {
+  /** Entry identifier. */
+  id: string;
+  /** Source BRAIN table (e.g. `observation`, `decision`, `pattern`, `learning`). */
+  type: string;
+  /** Display title for the entry. */
+  title: string;
+  /** Full text payload (narrative / decision text / pattern body / learning insight). */
+  text: string;
+  /** Fused relevance score: FTS50% + vector40% + graph10% × qualityScore. */
+  score: number;
+  /** Estimated token cost for this entry (~chars/4). */
+  tokensEstimated: number;
+  /** Memory tier for this entry. */
+  memoryTier?: string;
+  /** Cognitive type for this entry. */
+  memoryType?: string;
+}
+
+// ── BudgetedResult ──────────────────────────────────────────────────
+
+/**
+ * Result envelope returned by `retrieveWithBudget`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BudgetedResult {
+  /** Entries selected within the requested token budget, ranked by fused score. */
+  entries: BudgetedEntry[];
+  /** Total tokens consumed by returned entries. */
+  tokensUsed: number;
+  /** Tokens remaining from the original budget. */
+  tokensRemaining: number;
+  /** Number of entries excluded due to budget constraints. */
+  excluded: number;
+}

package/src/memory/fetch.ts

@@ -0,0 +1,66 @@
+/**
+ * BRAIN entry-fetch wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `fetchBrainEntries` operation — Layer 3 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Returns the full row payload for a
+ * caller-supplied list of IDs, typically derived from a prior `searchBrainCompact`
+ * or `timelineBrain` call.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 1: {@link ./search.ts}
+ * @see Layer 2: {@link ./timeline.ts}
+ */
+
+// ── FetchBrainEntriesParams ─────────────────────────────────────────
+
+/**
+ * Parameters for `fetchBrainEntries`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface FetchBrainEntriesParams {
+  /** Entry identifiers to fetch in a single batch. */
+  ids: string[];
+}
+
+// ── FetchedBrainEntry ───────────────────────────────────────────────
+
+/**
+ * A single fetched entry with its full row payload.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface FetchedBrainEntry {
+  /** Entry identifier. */
+  id: string;
+  /** Source BRAIN table (e.g. `observation`, `decision`, `pattern`, `learning`). */
+  type: string;
+  /**
+   * Raw row payload as returned by the underlying SQL query.
+   *
+   * Typed as `unknown` because the shape varies by `type`. Callers narrow
+   * via a discriminated read or pass the value through to a renderer.
+   */
+  data: unknown;
+}
+
+// ── FetchBrainEntriesResult ─────────────────────────────────────────
+
+/**
+ * Result envelope returned by `fetchBrainEntries`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface FetchBrainEntriesResult {
+  /** Resolved entries, in the order they were found (not necessarily input order). */
+  results: FetchedBrainEntry[];
+  /** Entry identifiers that could not be resolved against any BRAIN table. */
+  notFound: string[];
+  /** Approximate token cost of the returned payload (~chars/4). */
+  tokensEstimated: number;
+}