/**
 * BRAIN Observe — unified write path for observations + embedding backfill.
 *
 * @task T5134
 * @epic T5149
 */
import type { ObserveBrainParams, ObserveBrainResult } from '@cleocode/contracts';
/**
 * Save an observation to the BRAIN observations table.
 * Replaces the external claude-mem save_observation pattern.
 *
 * Auto-classifies type from text if not provided. Generates a
 * unique ID with O- prefix + base36 timestamp.
 *
 * @param projectRoot - Project root directory
 * @param params - Observation data
 * @returns Created observation ID, type, and timestamp
 *
 * @example
 * ```ts
 * // Save a decision observation to the BRAIN.
 * // The result contains the auto-generated ID, classified type, and timestamp.
 * const result = await observeBrain('/path/to/project', {
 *   text: 'Decided to use ESM-only imports for better tree-shaking.',
 *   title: 'ESM-only import decision',
 *   type: 'decision',
 *   sourceType: 'session-debrief',
 * });
 *
 * console.assert(result.id.startsWith('O-'), 'ID uses O- prefix');
 * console.assert(result.type === 'decision', 'type preserved from params');
 * console.assert(typeof result.createdAt === 'string', 'createdAt is ISO timestamp');
 * ```
 */
export declare function observeBrain(projectRoot: string, params: ObserveBrainParams): Promise<ObserveBrainResult>;
/** Result from populateEmbeddings backfill. */
export interface PopulateEmbeddingsResult {
    processed: number;
    skipped: number;
    errors: number;
    /**
     * Why nothing was processed, when nothing was.
     *
     * A bare `{processed: 0, skipped: 0, errors: 0}` is indistinguishable
     * between "everything is already embedded" and "embeddings are switched off
     * or broken" — and for the whole of gh#1217 it silently meant the latter
     * while `brain.embedding.enabled` was true. Reporting the reason is the
     * difference between a no-op and an outage.
     *
     * Absent when work was actually attempted.
     *
     * @task T12129 (gh#1217)
     */
    inactiveReason?: 'no-provider' | 'provider-load-failed' | 'no-brain-db';
}
/**
 * Options for the embedding backfill pipeline.
 *
 * @example
 * ```ts
 * await populateEmbeddings(root, {
 *   batchSize: 25,
 *   onProgress: (current, total) => console.log(`${current}/${total}`),
 * });
 * ```
 */
export interface PopulateEmbeddingsOptions {
    /** Maximum items processed per batch cycle. Defaults to 50. */
    batchSize?: number;
    /**
     * Maximum observations embedded by this call, newest first (T13126). Bounds a
     * background batch so it cannot run for the whole backlog at once.
     * @defaultValue undefined — every unembedded observation.
     */
    limit?: number;
    /**
     * Progress callback invoked after each observation is attempted.
     * `current` is the 1-based count of observations attempted so far;
     * `total` is the full count of observations that need embeddings.
     */
    onProgress?: (current: number, total: number) => void;
}
/**
 * Backfill embeddings for memory rows that lack a current one.
 *
 * Iterates through current observations, decisions, learnings and patterns
 * that have no vector, or a vector from a different model (T13740), and
 * generates vectors using the registered embedding provider.
 * Processes in batches to avoid memory pressure.
 *
 * An optional {@link PopulateEmbeddingsOptions.onProgress} callback is called
 * after each observation is attempted, enabling callers to report progress.
 *
 * @param projectRoot - Project root directory
 * @param options - Optional batch size and progress callback
 * @returns Count of processed, skipped, and errored observations
 *
 * @epic T134
 * @task T142
 */
export declare function populateEmbeddings(projectRoot: string, options?: PopulateEmbeddingsOptions): Promise<PopulateEmbeddingsResult>;
//# sourceMappingURL=observe.d.ts.map