@cleocode/contracts 2026.5.95 → 2026.5.97

package/dist/memory/observe.d.ts

@@ -0,0 +1,158 @@
+/**
+ * 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';
+/**
+ * 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 declare const BRAIN_OBSERVATION_SOURCE_TYPES: readonly ["agent", "session-debrief", "claude-mem", "manual"];
+/**
+ * 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];
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+/**
+ * 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';
+}
+//# sourceMappingURL=observe.d.ts.map

package/dist/memory/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/memory/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIzD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,8BAA8B,+DAKjC,CAAC;AAEX;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAIzF;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,8FAA8F;IAC9F,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,IAAI,CAAC,EAAE,oBAAoB,CAAC;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IACzC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAClC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAID;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAID;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,+BAA+B;IAC9C,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,IAAI,EAAE,gBAAgB,CAAC;CACxB"}

package/dist/memory/observe.js

@@ -0,0 +1,46 @@
+/**
+ * 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)
+ */
+// ── 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',
+];
+//# sourceMappingURL=observe.js.map

package/dist/memory/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/memory/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,uEAAuE;AAEvE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG;IAC5C,OAAO;IACP,iBAAiB;IACjB,YAAY;IACZ,QAAQ;CACA,CAAC"}

package/dist/memory/search.d.ts

@@ -0,0 +1,137 @@
+/**
+ * BRAIN compact-search wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `searchBrainCompact` operation — Layer 1 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Returns index-level hits (~50 tokens
+ * per result) so agents can scan a wide candidate set cheaply before drilling
+ * into a specific entry.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION) so the Studio + CLI + downstream consumers can
+ * depend on the shape without importing core. Unblocks the
+ * `brain-retrieval.ts` god-module split tracked under E-CORE-DECOMP
+ * (T9834).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 2: {@link ./timeline.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+/**
+ * Single compact hit returned by `searchBrainCompact`.
+ *
+ * Minimal projection of a BRAIN table row designed for cheap scanning —
+ * the full payload is fetched on demand via `fetchBrainEntries` (Layer 3).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BrainCompactHit {
+    /** Entry identifier (e.g. `D-arch-001`, `P-feat-042`). */
+    id: string;
+    /** Source BRAIN table that produced the hit. */
+    type: 'decision' | 'pattern' | 'learning' | 'observation';
+    /** Display title for the entry. */
+    title: string;
+    /** ISO 8601 creation date. */
+    date: string;
+    /** Legacy relevance score (BM25-only path); omit when `rrfScore` is set. */
+    relevance?: number;
+    /**
+     * RRF-fused score: sum of 1/(rank+60) across all retrieval sources.
+     * Present only when the RRF path is used (`useRRF=true`, default).
+     * Higher = stronger match. Comparable across results in the same query.
+     */
+    rrfScore?: number;
+    /**
+     * BM25-derived score, min-max normalized to [0, 1] across the result set.
+     * 1.0 = best BM25 rank in this query, 0.0 = worst (or not found via FTS).
+     * Present only when the RRF path is used and at least one FTS result exists.
+     */
+    bm25Score?: number;
+    /**
+     * Progressive-disclosure directives for follow-up operations.
+     *
+     * Maps follow-up keys (e.g. `fetch`, `timeline`) to suggested CLI commands.
+     * `Record<string, string>` mirrors the runtime `NextDirectives` alias used
+     * by `@cleocode/core`'s `mvi-helpers`.
+     */
+    _next?: Record<string, string>;
+}
+/**
+ * Parameters for `searchBrainCompact`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface SearchBrainCompactParams {
+    /** Free-text query (FTS5 + optional vector recall). */
+    query: string;
+    /** Maximum number of hits to return (caller-bounded). */
+    limit?: number;
+    /** Restrict the search to a subset of BRAIN tables. */
+    tables?: Array<'decisions' | 'patterns' | 'learnings' | 'observations'>;
+    /** ISO 8601 lower-bound date filter (inclusive). */
+    dateStart?: string;
+    /** ISO 8601 upper-bound date filter (inclusive). */
+    dateEnd?: string;
+    /** T418: filter results to observations produced by a specific agent (Wave 8 mental models). */
+    agent?: string;
+    /**
+     * When true (default), use Reciprocal Rank Fusion to combine FTS5 and
+     * vector search results for higher recall and better ranking.
+     * When false, fall back to FTS5-only search (faster, no embeddings needed).
+     */
+    useRRF?: boolean;
+    /**
+     * T1085: Peer ID filter for CANT agent memory isolation (PSYCHE Wave 2).
+     *
+     * When provided, search results are scoped to entries where:
+     *   `peer_id = peerId OR peer_id = 'global'`
+     *
+     * When omitted, all entries are returned — backward-compatible behavior.
+     */
+    peerId?: string;
+    /**
+     * T1085: When true (default when peerId is provided), include entries with
+     * `peer_id = 'global'` alongside the peer-specific entries.
+     *
+     * Set to false for strict per-peer isolation (no global pool bleed-through).
+     */
+    includeGlobal?: boolean;
+    /**
+     * T1900: ranking mode.
+     *
+     * - `recency`  — ORDER BY created_at DESC, no BM25/RRF contribution.
+     *                Use for recentObservations / recentLearnings where
+     *                chronological freshness matters more than textual match.
+     * - `lexical`  — FTS5 BM25 only (useRRF=false legacy path).
+     * - `hybrid`   — Reciprocal Rank Fusion (default, useRRF=true path).
+     *
+     * @default 'hybrid'
+     */
+    mode?: 'recency' | 'lexical' | 'hybrid';
+    /**
+     * T1900: ISO 8601 timestamp lower-bound filter (inclusive).
+     *
+     * When provided, only rows with `created_at >= since` are returned.
+     * Applies to all modes including recency. Useful with `mode=hybrid`
+     * (e.g., `since=<30d>`) to limit pattern staleness.
+     *
+     * When omitted, no lower-bound date filter is applied.
+     */
+    since?: string;
+}
+/**
+ * Result envelope returned by `searchBrainCompact`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface SearchBrainCompactResult {
+    /** Ordered compact hits (best match first). */
+    results: BrainCompactHit[];
+    /** Total number of matches before `limit` truncation. */
+    total: number;
+    /** Approximate token cost of the returned payload (~chars/4). */
+    tokensEstimated: number;
+}
+//# sourceMappingURL=search.d.ts.map

package/dist/memory/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/memory/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,CAAC;IAC1D,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAID;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,MAAM,CAAC,EAAE,KAAK,CAAC,WAAW,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC,CAAC;IACxE,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IACxC;;;;;;;;OAQG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,+CAA+C;IAC/C,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,eAAe,EAAE,MAAM,CAAC;CACzB"}

package/dist/memory/search.js

@@ -0,0 +1,22 @@
+/**
+ * BRAIN compact-search wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `searchBrainCompact` operation — Layer 1 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Returns index-level hits (~50 tokens
+ * per result) so agents can scan a wide candidate set cheaply before drilling
+ * into a specific entry.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION) so the Studio + CLI + downstream consumers can
+ * depend on the shape without importing core. Unblocks the
+ * `brain-retrieval.ts` god-module split tracked under E-CORE-DECOMP
+ * (T9834).
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 2: {@link ./timeline.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+export {};
+//# sourceMappingURL=search.js.map

package/dist/memory/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/memory/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/memory/timeline.d.ts

@@ -0,0 +1,89 @@
+/**
+ * BRAIN timeline wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `timelineBrain` operation — Layer 2 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Surfaces chronological neighbors
+ * around an anchor entry so an agent can reconstruct the surrounding
+ * memory context cheaply.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION). `BrainAnchor` is co-located here because it
+ * is the only `brain-row-types.ts` shape that escapes the core boundary
+ * via `TimelineBrainResult`; `packages/core/src/memory/brain-row-types.ts`
+ * continues to re-export it for internal callers.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 1: {@link ./search.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+/**
+ * Anchor entry around which a timeline is built.
+ *
+ * Carries the entry identifier, its source table (`type`), and the full
+ * payload (`data`) so the caller can render the anchor inline with the
+ * neighbor list without an additional `fetchBrainEntries` round trip.
+ *
+ * Originally defined in `packages/core/src/memory/brain-row-types.ts:46`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface BrainAnchor {
+    /** Entry identifier (e.g. `O-abc123`, `D-arch-001`). */
+    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 that
+     * already understands every BRAIN table shape.
+     */
+    data: unknown;
+}
+/**
+ * Parameters for `timelineBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineBrainParams {
+    /** Anchor entry ID to build the timeline around. */
+    anchor: string;
+    /** Number of chronologically-earlier neighbors to include. */
+    depthBefore?: number;
+    /** Number of chronologically-later neighbors to include. */
+    depthAfter?: number;
+}
+/**
+ * Compact neighbor projection used in timeline results.
+ *
+ * Each neighbor is reduced to an `{id, type, date}` triple so callers can
+ * cheaply scan a large window before drilling into specific entries via
+ * `fetchBrainEntries`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineNeighbor {
+    /** Entry identifier. */
+    id: string;
+    /** Source BRAIN table (e.g. `observation`, `decision`). */
+    type: string;
+    /** ISO 8601 creation date. */
+    date: string;
+}
+/**
+ * Result envelope returned by `timelineBrain`.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ */
+export interface TimelineBrainResult {
+    /** The anchor entry, or `null` when the requested ID does not resolve. */
+    anchor: BrainAnchor | null;
+    /** Chronologically-earlier neighbors, oldest first. */
+    before: TimelineNeighbor[];
+    /** Chronologically-later neighbors, newest last. */
+    after: TimelineNeighbor[];
+}
+//# sourceMappingURL=timeline.d.ts.map

package/dist/memory/timeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.d.ts","sourceRoot":"","sources":["../../src/memory/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,WAAW;IAC1B,wDAAwD;IACxD,EAAE,EAAE,MAAM,CAAC;IACX,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAC;IACb;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAID;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,oDAAoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID;;;;;;;;GAQG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAID;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,uDAAuD;IACvD,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,oDAAoD;IACpD,KAAK,EAAE,gBAAgB,EAAE,CAAC;CAC3B"}

package/dist/memory/timeline.js

@@ -0,0 +1,22 @@
+/**
+ * BRAIN timeline wire shapes.
+ *
+ * Canonical home for the parameters and result types of the public
+ * `timelineBrain` operation — Layer 2 of CLEO's 3-layer BRAIN retrieval
+ * pattern (search → timeline → fetch). Surfaces chronological neighbors
+ * around an anchor entry so an agent can reconstruct the surrounding
+ * memory context cheaply.
+ *
+ * Promoted from `packages/core/src/memory/brain-retrieval.ts` to
+ * `@cleocode/contracts` in Phase 0e of SG-ARCH-SOLID
+ * (E-CONTRACTS-FOUNDATION). `BrainAnchor` is co-located here because it
+ * is the only `brain-row-types.ts` shape that escapes the core boundary
+ * via `TimelineBrainResult`; `packages/core/src/memory/brain-row-types.ts`
+ * continues to re-export it for internal callers.
+ *
+ * @since SG-ARCH-SOLID Saga T9831 · E-CONTRACTS-FOUNDATION T9832 · T9956 (Phase 0e)
+ * @see Layer 1: {@link ./search.ts}
+ * @see Layer 3: {@link ./fetch.ts}
+ */
+export {};
+//# sourceMappingURL=timeline.js.map

package/dist/memory/timeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeline.js","sourceRoot":"","sources":["../../src/memory/timeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}