/**
 * `JsonlLog<T>` — an append-only, schema-validated event log.
 *
 * Where {@link import("./json-cell").JsonCell} owns a single mutable value,
 * a log owns an immutable, ever-growing sequence. Entries are stored one JSON
 * object per line (NDJSON / JSONL): appending is a single `appendFile`, and
 * reading is a line scan. Immutability is the point — nothing rewrites earlier
 * lines, which makes appends cheap and concurrent-append-safe without a
 * read-modify-write transaction.
 *
 * Two surfaces:
 *
 *   - {@link JsonlLog.append} / {@link JsonlLog.readAll} — the core log.
 *     Every entry is validated against the cell's zod schema on the way in and
 *     on the way out, so a corrupt line is caught rather than silently trusted.
 *   - {@link JsonlLog.threadOf} — a parent-pointer tree helper. When entries
 *     carry an `id` and an optional `parentId`, this walks the parent chain
 *     from a leaf back to its root, returning the lineage root→…→leaf. This is
 *     the conversation/reply-threading pattern, kept as a *pattern* only:
 *     fresh code, generic over any entry that exposes those two fields.
 *
 * The log is deliberately not a mutex-guarded value. POSIX append writes of a
 * single short line are atomic enough for our append-only use; correctness here
 * comes from never mutating existing lines, not from locking.
 */
import { type ZodType } from "zod";
/**
 * The minimal shape an entry must expose to participate in {@link
 * JsonlLog.threadOf}. The log's own type `T` only needs to be assignable to
 * this when `threadOf` is used; plain `append`/`readAll` impose no such
 * constraint.
 */
export interface TreeNode {
    /** This entry's own id. */
    readonly id: string;
    /** The id of the entry this one descends from, if any. */
    readonly parentId?: string | null;
}
/**
 * An append-only JSONL log of `T`, validated against a zod schema.
 *
 * Open with {@link JsonlLog.open}; the factory ensures the parent directory
 * exists so the first {@link append} cannot fail on a missing folder.
 */
export declare class JsonlLog<T> {
    /** Absolute path of the `.jsonl` file backing this log. */
    readonly path: string;
    private readonly schema;
    private constructor();
    /** Open (or adopt) the log at `path`, ensuring its parent directory exists. */
    static open<T>(path: string, schema: ZodType<T>): Promise<JsonlLog<T>>;
    /**
     * Validate and append one entry as a single JSONL line.
     *
     * The entry is run through the schema first; a rejection raises a
     * `validation` fault before anything touches disk. Returns the entry as
     * validated/normalized by the schema.
     */
    append(entry: T): Promise<T>;
    /**
     * Read and validate every entry, in append order.
     *
     * A missing file is an empty log, not an error. Blank lines are skipped. A
     * line that is not valid JSON, or that fails the schema, raises a
     * `validation` fault naming the offending line number.
     */
    readAll(): Promise<T[]>;
    /**
     * Resolve the ancestry chain ending at `id`, root-first.
     *
     * Reads the whole log, indexes entries by `id`, then walks `parentId`
     * pointers from the named leaf up to a root (an entry with no resolvable
     * parent), and returns the chain in root→…→leaf order. A `not_found` fault is
     * raised if `id` itself is absent; a `conflict` fault is raised if the parent
     * chain contains a cycle. Entries whose `parentId` points at a missing id are
     * treated as roots (the chain simply stops there).
     *
     * Only available when the log's `T` exposes {@link TreeNode}'s fields.
     */
    threadOf(this: JsonlLog<T & TreeNode>, id: string): Promise<(T & TreeNode)[]>;
}
