/** Why `readAll` skipped a file that matched the suffix.
 *  `'unreadable'` — the file could not be read or did not parse as JSON.
 *  `'invalid'`    — it parsed but failed the store's `validate`. */
export type SidecarSkipReason = 'unreadable' | 'invalid';
export type WriteResult = {
    ok: true;
} | {
    ok: false;
    error: unknown;
};
export type ClearResult = {
    ok: true;
    removed: boolean;
} | {
    ok: false;
    error: unknown;
};
export interface SidecarStore<T> {
    /** `<sessionsDir>/<id><suffix>`. */
    pathFor(sessionsDir: string, id: string): string;
    /** Atomic write of `record` as JSON (no indentation): create the dir, write a
     *  `<path>.tmp.<pid>` sibling, then rename it onto the canonical path. On
     *  failure the tmp file is removed best-effort and the caught error is
     *  returned rather than thrown — the caller owns the success/failure log. */
    write(sessionsDir: string, id: string, record: T): WriteResult;
    /** Read + parse + validate one record. Null when the file is absent,
     *  unreadable, not JSON, or fails `validate`. */
    read(sessionsDir: string, id: string): T | null;
    /** Every valid record in `sessionsDir`. Files not matching the suffix are
     *  ignored. A matching file that is unreadable/not-JSON fires
     *  `onSkip(name, 'unreadable')`; one that parses but fails `validate` fires
     *  `onSkip(name, 'invalid')`. A missing directory yields `[]`. */
    readAll(sessionsDir: string, onSkip?: (fileName: string, reason: SidecarSkipReason) => void): T[];
    /** `existsSync` + `unlink`. `{ ok: true, removed: false }` when the file was
     *  already absent; `{ ok: false, error }` when the unlink throws. */
    clear(sessionsDir: string, id: string): ClearResult;
}
export declare function createSidecarStore<T>(config: {
    /** Filename suffix including the dot(s), e.g. `'.scope.json'`. */
    suffix: string;
    /** Parse-validate one decoded JSON value into a record, or null if it does
     *  not match the store's shape. */
    validate: (raw: unknown) => T | null;
}): SidecarStore<T>;
//# sourceMappingURL=sidecar-store.d.ts.map