import type { CompiledDefinition } from '../core/types.js';
/** One block's worth of a document's live records, as the door answers them:
 *  the records are the op store's cells verbatim (identity included — the
 *  server minted it, the server serves it), and `readAt` is the working-layer
 *  revision (`op-<seq>`) these records were read at — what the mirror's
 *  header stores per block. */
export interface PulledBlock {
    block: string;
    readAt: string;
    records: Record<string, unknown>[];
}
export interface PulledDocument {
    document: string;
    blocks: PulledBlock[];
}
/** `GET /api/:org/:kb/ops/records` — the whole KB's live operational records,
 *  grouped by document. The cloud half of this contract lands beside this
 *  one; the shape is pinned by test/pull.test.ts's mock exactly the way
 *  cloud-cli.test.ts pins the rows door. */
export interface PullRecordsAnswer {
    readAt: string;
    documents: PulledDocument[];
}
export interface PlannedMirror {
    /** vault-relative `.records.local.yaml` path */
    path: string;
    /** header + serialized records, ready to write verbatim */
    text: string;
}
/**
 * Every document's mirror file, or ONE refusal for the whole pull.
 *
 * The refusals are total on purpose: a mirror written from a format that
 * disagrees with the host's would either drop records silently (an unknown
 * block skipped) or write a file the engine's own filename law refuses
 * (`sidecar-local-canonical`, a canonical block in a `.records.local.yaml`).
 * Both mean the LOCAL format.yaml is behind the KB's — the fix is to update
 * it, and a half-mirror would hide exactly that.
 */
export declare function planPullMirror(answer: PullRecordsAnswer, def: CompiledDefinition, header: {
    host: string;
    kb: string;
    at: string;
}): {
    files: PlannedMirror[];
} | {
    refusal: string;
};
export declare const LOCAL_SIDECAR_IGNORE = "*.records.local.yaml";
/**
 * The next `.gitignore` text, or null when nothing needs writing.
 *
 * The mirror files this command writes must never be committed — a committed
 * one is refused by the referee by name (`sidecar-local-committed`) — so the
 * command that CREATES them owns keeping them ignored: relying on the person
 * to remember is how the finding fires in the first place. The check is a
 * whole-line match over trimmed lines (comments and blank lines fall out
 * naturally), so re-running pull is byte-neutral on a file that already
 * carries the pattern — ONE stable pattern, `*.records.local.yaml`, exactly
 * as L6 promises; never a per-document entry, never a second spelling that
 * could accumulate.
 */
export declare function ensureLocalSidecarIgnored(gitignore: string | null): string | null;
export interface PullOptions {
    /** the only thing pull fetches today — required, so a future `dj pull`
     *  that also syncs something else keeps this call's meaning */
    records?: boolean;
    kb?: string;
    host?: string;
    json?: boolean;
    vault?: string;
    /** path to format.yaml — the mirror is serialized against the LOCAL
     *  definition's column order, which is also what reads it back */
    format?: string;
}
export declare function cmdPull(opts: PullOptions): Promise<number>;