/**
 * Pre-compact Flush — capture in-flight session observations before context compaction.
 *
 * When Claude Code's context window approaches the compaction threshold, this
 * module flushes any pending diary-type observations captured during the current
 * session to `brain_observations` so that no context is lost across the
 * compaction boundary.
 *
 * It also runs `PRAGMA wal_checkpoint(TRUNCATE)` on brain.db to ensure all
 * WAL frames are flushed to the main database file before compaction occurs.
 *
 * Design constraints:
 * - Must complete in < 5 s (30-second hook timeout window).
 * - Must be a graceful no-op when no pending observations are present.
 * - Must be idempotent: a second call after a successful flush does nothing.
 *
 * @module precompact-flush
 * @task T1004
 * @epic T1000
 */
/** A pending observation captured in process memory awaiting flush. */
export interface PendingObservation {
    /** Observation text / content. */
    text: string;
    /** Optional human-readable title. */
    title?: string;
    /** Observation type. Falls back to 'discovery' if 'diary' is not yet in schema. */
    type?: string;
    /** Session ID that originated this observation. */
    sessionId?: string;
}
/** Result returned by {@link precompactFlush}. */
export interface PrecompactFlushResult {
    /** Number of observations persisted to brain_observations. */
    flushed: number;
    /** Whether the WAL checkpoint was executed. */
    walCheckpointed: boolean;
    /** Any non-fatal error messages encountered (flush is best-effort). */
    errors: string[];
}
/**
 * Register an observation that should be flushed at the next pre-compact hook.
 *
 * Call this function whenever an agent captures context that has not yet been
 * persisted to brain.db (e.g. work-in-progress notes, mid-task decisions).
 *
 * @param obs - The observation to queue for flush.
 */
export declare function enqueuePendingObservation(obs: PendingObservation): void;
/**
 * Return a snapshot of the current pending queue (for testing / inspection).
 * Does not mutate the queue.
 *
 * @returns Readonly copy of the pending observations.
 */
export declare function getPendingObservations(): readonly PendingObservation[];
/**
 * Clear the pending observation queue.
 * Called internally after a successful flush, and exposed for testing.
 */
export declare function clearPendingObservations(): void;
/**
 * Flush all pending in-flight observations to brain.db and checkpoint the WAL.
 *
 * Steps performed:
 * 1. Collect all observations from the in-process pending queue.
 * 2. Persist each observation via `observeBrain` with `sourceType='agent'`.
 * 3. Run `PRAGMA wal_checkpoint(TRUNCATE)` on brain.db.
 * 4. Clear the pending queue so a second call is a no-op.
 *
 * Returns `{flushed: 0, walCheckpointed: false, errors: []}` when there are
 * no pending observations and brain.db has not yet been initialised in this
 * process (lazy DB init guard).
 *
 * Never throws — all errors are captured in the `errors` array so that hook
 * failures do not interrupt Claude Code's compaction sequence.
 *
 * @param projectRoot - Absolute path to the project root directory.
 *                      Defaults to `process.cwd()`.
 * @returns Flush result summary.
 */
export declare function precompactFlush(projectRoot?: string): Promise<PrecompactFlushResult>;
//# sourceMappingURL=precompact-flush.d.ts.map