/**
 * Async reinforcement queue for non-blocking mental-model writes.
 *
 * ULTRAPLAN L5 compliance: observations tagged with an `agent` provenance and a
 * mental-model-relevant type ('discovery', 'change', 'feature', 'decision') are
 * routed through this queue instead of writing synchronously to brain.db. This
 * decouples the hot path (agent execution) from I/O latency.
 *
 * The queue is drained to brain.db either:
 *   1. Periodically — every {@link FLUSH_INTERVAL_MS} milliseconds via a timer.
 *   2. On high watermark — when the queue exceeds {@link FLUSH_WATERMARK} entries.
 *   3. On process exit — SIGINT, SIGTERM, and 'exit' hooks perform a best-effort
 *      synchronous flush so no observations are lost.
 *
 * Observations without an `agent` field continue to use the existing synchronous
 * path in observeBrain() and are never routed here.
 *
 * @task T383/T419
 * @epic T377
 */
import type { ObserveBrainParams, ObserveBrainResult } from './brain-retrieval.js';
/**
 * Public interface for the mental-model queue singleton.
 *
 * @example
 * ```ts
 * const q = getMentalModelQueue();
 * await q.enqueue(projectRoot, { text: 'Agent learned X', agent: 'my-agent', ... });
 * const remaining = q.size();
 * await q.flush();
 * ```
 */
export interface MentalModelQueue {
    /**
     * Enqueue a mental-model observation for async write.
     *
     * Returns a Promise that resolves with the persisted {@link ObserveBrainResult}
     * once the batch flush runs. Non-blocking for the caller.
     *
     * @param projectRoot - Project root directory for the brain.db path.
     * @param params - Observation parameters. MUST include `agent`.
     */
    enqueue(projectRoot: string, params: ObserveBrainParams & {
        agent: string;
    }): Promise<ObserveBrainResult>;
    /**
     * Drain the queue immediately.
     *
     * Writes all pending observations to brain.db.
     * Safe to call concurrently — duplicate calls are serialised internally.
     *
     * @returns The number of observations successfully drained.
     */
    flush(): Promise<number>;
    /** Current number of pending observations in the queue. */
    size(): number;
}
/**
 * Mental-model queue singleton.
 *
 * Use this instead of calling observeBrain() directly when writing agent-tagged
 * observations that should be queued for async persistence (ULTRAPLAN L5).
 */
export declare const mentalModelQueue: MentalModelQueue;
/**
 * Reset in-process queue state.
 *
 * Stops the flush timer, rejects any pending observations with a cancellation
 * error, and clears internal flags. Intended for test teardown only — never
 * call this in production code.
 *
 * @internal
 */
export declare function _resetMentalModelQueueForTests(): void;
/**
 * Determine whether an observation should be routed through the mental-model
 * queue rather than written synchronously.
 *
 * Returns `true` when the observation has a non-empty `agent` field AND a
 * mental-model-relevant type.
 *
 * @param params - Observation parameters to evaluate.
 */
export declare function isMentalModelObservation(params: ObserveBrainParams): boolean;
//# sourceMappingURL=mental-model-queue.d.ts.map