@cleocode/contracts 2026.5.95 → 2026.5.97

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,8 +299,15 @@ export {
   DocKindConfigError,
   DocKindRegistry,
 } from './docs-taxonomy.js';
-// === Doctor: Worktree-Orphan Audit + Prune Types (T9790) ===
-export type { OrphanEntry, PruneAuditEntry, PruneResult } from './doctor.js';
+// === Doctor: Worktree-Orphan Audit + Prune Types (T9790, T9808) ===
+export type {
+  ComprehensiveAuditResult,
+  OrphanEntry,
+  PruneAuditEntry,
+  PruneResult,
+  WorktreeAnomaly,
+  WorktreeAnomalyKind,
+} from './doctor.js';
 export type {
   EngineErrorPayload,
   EngineFailure,
@@ -310,6 +322,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,
@@ -437,6 +458,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,
@@ -523,8 +546,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,
@@ -1040,6 +1092,7 @@ export type {
   DepGraphIssue,
   DepsTreeEdge,
   DepsTreeNode,
+  TaskShowAttachmentEntry,
   TasksAddBatchParams,
   TasksAddBatchResult,
   TasksAddParams,
@@ -1192,6 +1245,8 @@ export type {
 // Re-exported at top level so @cleocode/worktree and callers can
 // import without the `ops.` namespace hop.
 export type {
+  AdoptWorktreeOpts,
+  AdoptWorktreeResult,
   CreateWorktreeOptions,
   CreateWorktreeResult,
   DestroyWorktreeOptions,
@@ -1213,6 +1268,7 @@ export type {
   WorktreeLifecycleAction,
   WorktreeLifecycleAuditEntry,
   WorktreeListEntry,
+  WorktreeSource,
   WorktreeStatusCategory,
 } from './operations/worktree.js';
 // === Orchestration Roll-up Types (T9082, ADR-070) ===
@@ -1273,6 +1329,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';
@@ -1399,6 +1479,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;
+}

package/src/memory/observe.ts

@@ -0,0 +1,176 @@
+/**
+ * BRAIN observation-write wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `observeBrain` operation — the unified BRAIN write path that persists
+ * agent observations into `brain_observations`. Companion to the
+ * read-side trio in {@link ./search.ts}, {@link ./timeline.ts}, and
+ * {@link ./fetch.ts}.
+ *
+ * The `BRAIN_OBSERVATION_SOURCE_TYPES` const is co-located here so the
+ * derived `BrainObservationSourceType` union has a single source of truth.
+ * `packages/core/src/store/memory-schema.ts` re-exports the const for
+ * Drizzle's `enum: [...]` column constraint, which requires the runtime
+ * tuple literal.
+ *
+ * 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)
+ */
+
+import type { BrainSourceConfidence } from '../brain.js';
+import type { BrainObservationType } from '../facade.js';
+
+// ── BRAIN_OBSERVATION_SOURCE_TYPES + BrainObservationSourceType ─────
+
+/**
+ * Source-type tuple for `brain_observations.source_type` — how the
+ * observation was created.
+ *
+ * Originally defined in `packages/core/src/store/memory-schema.ts:134`.
+ * Promoted here so the derived {@link BrainObservationSourceType} union
+ * lives alongside its source. `memory-schema.ts` re-exports the const
+ * because Drizzle's `{ enum: ... }` column constraint requires the runtime
+ * tuple literal.
+ *
+ * - `agent`           — produced by a spawned agent at task time.
+ * - `session-debrief` — synthesized at session end by the debrief pipeline.
+ * - `claude-mem`      — imported from a claude-mem migration batch.
+ * - `manual`          — typed directly by the owner via `cleo memory observe`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export const BRAIN_OBSERVATION_SOURCE_TYPES = [
+  'agent',
+  'session-debrief',
+  'claude-mem',
+  'manual',
+] as const;
+
+/**
+ * Derived string-literal union of valid `source_type` values.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export type BrainObservationSourceType = (typeof BRAIN_OBSERVATION_SOURCE_TYPES)[number];
+
+// ── ObserveBrainParams ──────────────────────────────────────────────
+
+/**
+ * Parameters for `observeBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface ObserveBrainParams {
+  /** Observation narrative — the free-form text persisted to `brain_observations.narrative`. */
+  text: string;
+  /** Optional display title; auto-derived from `text` when omitted. */
+  title?: string;
+  /** Optional cognitive observation type (`feature`, `bugfix`, `decision`, …). */
+  type?: BrainObservationType;
+  /** Optional project scope ID; defaults to the current project root. */
+  project?: string;
+  /** Session ID that produced the observation (provenance). */
+  sourceSessionId?: string;
+  /** How the observation was created (default `agent`). */
+  sourceType?: BrainObservationSourceType;
+  /** T417: agent provenance — the name of the spawned agent producing this observation. */
+  agent?: string;
+  /**
+   * T549 Wave 1-A: source reliability level.
+   * Overrides the default routing. If omitted, routing is determined automatically:
+   * - sourceType 'manual' → 'owner'
+   * - sourceType 'session-debrief' → 'task-outcome'
+   * - otherwise → 'agent'
+   */
+  sourceConfidence?: BrainSourceConfidence;
+  /**
+   * T794 BRAIN-05: cross-references to other memory entries or external IDs.
+   * When this array has ≥1 entry, the observation is auto-promoted from
+   * 'short' to 'medium' tier at write time to protect it from soft-eviction.
+   */
+  crossRef?: string[];
+  /**
+   * T799: SHA-256 refs of attachments to link to this observation.
+   *
+   * Stored as a JSON-encoded string in the `attachments_json` column.
+   * Each entry must be a 64-char hex SHA-256 from the tasks.db attachment store.
+   */
+  attachmentRefs?: string[];
+  /**
+   * T1897: Producer pipeline that created this observation.
+   * - `manual`           — typed directly by owner
+   * - `auto-extract`     — from fulfillPromotionLog / LLM extraction
+   * - `transcript-ingest`— imported from raw session transcript
+   * - `session-debrief`  — synthesized at session end
+   * - `test`             — inserted by test code
+   *
+   * Null on legacy rows and when not specified.
+   */
+  origin?: string | null;
+  /**
+   * T1897: JSON array of source brain_observations.id values this row was derived from.
+   * Null for directly-observed rows.
+   */
+  provenanceChain?: string[] | null;
+  /**
+   * T992: Internal flag — when true, bypasses the verifyAndStore gate.
+   * Set only by storeVerifiedCandidate in extraction-gate.ts to avoid
+   * infinite recursion (gate → storeVerifiedCandidate → observeBrain → gate).
+   * External callers MUST NOT set this flag.
+   */
+  _skipGate?: boolean;
+}
+
+// ── ObserveBrainResult ──────────────────────────────────────────────
+
+/**
+ * Result envelope returned by `observeBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface ObserveBrainResult {
+  /** Identifier of the newly-persisted observation row. */
+  id: string;
+  /** Resolved BRAIN table name (always `observation` for `observeBrain`). */
+  type: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+}
+
+// ── DocAttachmentObservationPayload ─────────────────────────────────
+
+/**
+ * Structured payload stored in the `narrative` of a doc-attachment memory
+ * observation emitted by `cleo docs add` (T9976).
+ *
+ * The observation title is `"Doc attached: <slug>"` (or
+ * `"Doc attached: <attachmentId>"` when no slug is set) so
+ * `cleo memory find '<slug>'` reliably surfaces the entry via FTS.
+ *
+ * The payload is serialised as JSON and embedded in the observation
+ * `narrative` field so it can be recovered by `cleo memory verify`
+ * for round-trip attachment-existence checks.
+ *
+ * @task T9976
+ */
+export interface DocAttachmentObservationPayload {
+  /** Slug recorded for this attachment (optional — omitted when none set). */
+  slug?: string;
+  /** Owner entity ID (task, session, observation, …). */
+  ownerId: string;
+  /** Taxonomy type classification (optional). */
+  type?: string;
+  /** Attachment ID assigned by the store. */
+  attachmentId: string;
+  /** ISO 8601 timestamp when the attachment was added. */
+  addedAt: string;
+  /**
+   * Observation kind discriminator — always `"doc-attachment"`.
+   * Used by `cleo memory verify` to identify doc-attachment observations
+   * and perform round-trip checks against the docs store.
+   */
+  kind: 'doc-attachment';
+}