/**
 * `JsonCell<T>` — the one abstraction the swarm kernel coordinates through.
 *
 * The old crew layer hand-rolled the same three-step dance in four different
 * files: take a cooperative file lock, read-and-validate the JSON, write it
 * back atomically. This module collapses that trio into a single, well-tested
 * class so every domain service (manifest, ticket board, channel, lease) is a
 * thin wrapper over it rather than another copy of the pattern.
 *
 * A cell owns exactly one JSON file plus a zod schema describing its contents:
 *
 *   - {@link JsonCell.read} — load the file, validate against the schema, and
 *     return a typed value. A missing file yields the cell's `initial` value;
 *     malformed JSON or a schema mismatch raises a `validation` fault.
 *   - {@link JsonCell.mutate} — the transactional primitive. It takes an
 *     exclusive lock, reads+validates the current value, applies the caller's
 *     pure transform, re-validates the result, atomically publishes it
 *     (temp file → `rename`), and releases the lock — even on error.
 *
 * Three deliberate divergences from the prior art:
 *
 *   1. **mkdir-lock, not `O_EXCL`.** The mutex is an atomic `mkdir` of a
 *      `<file>.lockdir` directory. `mkdir` is atomic on POSIX and Windows and
 *      fails with `EEXIST` when the directory already exists, giving the same
 *      single-writer guarantee as an exclusive-create lockfile without opening
 *      a file handle. A small JSON marker is dropped *inside* the lock dir for
 *      stale detection and debuggability.
 *   2. **Our own backoff.** Acquisition retries on a jittered exponential
 *      schedule bounded by a deadline; a lock dir older than `staleMs` is
 *      forcibly reclaimed (its owner is presumed dead).
 *   3. **Schema-validated on every crossing.** Reads and writes both run the
 *      passed zod schema, so a cell can never persist or surface a value that
 *      violates its type. Validation failures are typed `SwarmFault`s carrying
 *      the originating `ZodError` as `cause`.
 */
import { type ZodType } from "zod";
/** Tunables for the exclusive-guard acquisition loop. */
export interface GuardOptions {
    /** Hard deadline for acquiring the lock, in ms. Default 10_000. */
    readonly timeoutMs?: number;
    /** A lock dir older than this (by marker/mtime age) is reclaimed. Default 30_000. */
    readonly staleMs?: number;
    /** First backoff sleep, in ms; subsequent sleeps grow exponentially. Default 12. */
    readonly baseDelayMs?: number;
    /** Ceiling on any single backoff sleep, in ms. Default 250. */
    readonly maxDelayMs?: number;
}
/**
 * A lockable, schema-validated, atomically-published JSON file.
 *
 * Construct one with {@link JsonCell.open}; never `new` it directly — the
 * factory is `async` so it can ensure the parent directory exists up front.
 */
export declare class JsonCell<T> {
    /** Absolute path of the JSON file this cell owns. */
    readonly path: string;
    private readonly schema;
    private readonly initial;
    private readonly guardOpts;
    private constructor();
    /**
     * Open (or adopt) the cell at `path`.
     *
     * The `initial` value is what {@link read} returns when the file does not yet
     * exist; it is validated against `schema` immediately so a bad default fails
     * loudly at open time rather than on first read. The file itself is *not*
     * eagerly created — it materializes on the first {@link mutate}. The parent
     * directory is created if missing.
     */
    static open<T>(path: string, schema: ZodType<T>, initial: T, guard?: GuardOptions): Promise<JsonCell<T>>;
    /**
     * Load and validate the current value.
     *
     * A missing file returns the cell's `initial` value (the cell is born empty,
     * not broken). Unparseable JSON or a schema mismatch raises a `validation`
     * fault. Reads are lock-free: thanks to atomic publish, a reader either sees
     * the previous complete value or the next complete value, never a torn one.
     */
    read(): Promise<T>;
    /**
     * Transactionally read-modify-write under the exclusive guard.
     *
     * Acquires the lock, reads+validates the current value, applies `fn`,
     * validates the result, atomically publishes it, and releases the lock in a
     * `finally`. `fn` must be pure and must not perform its own I/O on this cell
     * (it runs while the lock is held). Returns the freshly persisted value.
     */
    mutate(fn: (current: T) => T): Promise<T>;
    /** Parse + validate file text into a typed value. */
    private decode;
    /** Validate an outgoing value and serialize it. */
    private encode;
    /** Write to a unique temp sibling then `rename` over the target (atomic). */
    private publishAtomic;
    /** Path of this cell's lock directory. */
    private get lockDir();
    /**
     * Run `body` while holding this cell's exclusive guard.
     *
     * Acquisition is an atomic `mkdir` of the lock dir; on `EEXIST` we back off
     * and retry, reclaiming a lock dir that has gone stale. The lock is always
     * released, including when `body` throws.
     */
    private withGuard;
    /** Acquire the lock dir, backing off and breaking stale locks until the deadline. */
    private acquire;
    /** True when the held lock dir is older than `staleMs` (presumed abandoned). */
    private lockIsStale;
    /** Forcibly remove a stale lock dir so a fresh holder can take it. */
    private breakLock;
    /** Release the lock by removing its directory. Best-effort; never throws. */
    private release;
}
