/**
 * @fileoverview `defineMirror` — assembles a {@link MirrorStore}, a server's
 * `sync` generator, and the runner into a single owned mirror instance. The
 * returned object is what a server holds (one per mirror) and exposes to its
 * tools: `runSync`, `query`, `status`/`ready`, `getByIds`, and the raw handle.
 * @module services/mirror/core/defineMirror
 */
import type { MirrorDefinition, MirrorRow, MirrorStatus, MirrorStore, QueryOptions, QueryResult, RunSyncOptions, SqliteHandle, SyncResult } from '../types.js';
/** Options for a single {@link Mirror.runSync} call. */
export type MirrorRunOptions = RunSyncOptions & {
    /** Cancels the run; the runner persists state before stopping. Defaults to a never-aborting signal. */
    signal?: AbortSignal;
};
/** An owned mirror instance — the return value of {@link defineMirror}. */
export interface Mirror {
    /** Close the underlying store. */
    close(): Promise<void>;
    /** Fetch records by primary-key list, preserving input order. */
    getByIds(ids: string[]): Promise<MirrorRow[]>;
    /** Stable name from the definition. */
    readonly name: string;
    /** Generic flat query over the mirror. */
    query(options: QueryOptions): Promise<QueryResult>;
    /** The opened runtime-agnostic handle for server-specific access paths. */
    raw(): Promise<SqliteHandle>;
    /** `true` once a full sync has ever completed (queryable even mid-refresh). */
    ready(): Promise<boolean>;
    /** Run a full (`init`) or incremental (`refresh`) sync. */
    runSync(options: MirrorRunOptions): Promise<SyncResult>;
    /** Current sync status, including the durable `ready` marker. */
    status(): Promise<MirrorStatus>;
    /** The backing store (escape hatch for advanced use). */
    readonly store: MirrorStore;
}
/**
 * Assemble a mirror from a store, a `sync` generator, and a name. Nothing opens
 * until the first call; construction is cheap and side-effect-free.
 *
 * @example
 * ```ts
 * const papers = defineMirror({
 *   name: 'arxiv-papers',
 *   store: sqliteMirrorStore({
 *     path: config.mirrorPath,
 *     primaryKey: 'id',
 *     columns: { id: 'TEXT', title: 'TEXT', abstract: 'TEXT', updated: 'TEXT' },
 *     fts: ['title', 'abstract'],
 *     indexes: [{ columns: ['updated'] }],
 *   }),
 *   async *sync({ mode, cursor, checkpoint, signal }) {
 *     for await (const page of harvest({ cursor, since: checkpoint, signal })) {
 *       yield { records: page.rows, cursor: page.token, checkpoint: page.maxStamp };
 *     }
 *   },
 * });
 *
 * await papers.runSync({ mode: 'init', signal: AbortSignal.timeout(3_600_000) });
 * const { rows, total } = await papers.query({ match: 'transformers', limit: 10, offset: 0 });
 * ```
 */
export declare function defineMirror(definition: MirrorDefinition): Mirror;
//# sourceMappingURL=defineMirror.d.ts.map