/**
 * The durable application command mailbox (WFT-84).
 *
 * A mailbox is a storage-backed, strictly FIFO command queue scoped to one
 * opaque `(namespace, resourceId)` pair. Admission returns a durable receipt
 * that survives process restart; delivery is attempt-fenced so two consumers
 * can never both hold a valid claim; cancellation is durable before it reaches
 * anyone; and every state transition commits atomically with its fleet event
 * when an event sink is configured.
 *
 * What it is not: a message broker. There are no topics, no consumer groups, no
 * cross-mailbox ordering, and no cross-region replication. Ordering is defined
 * within one mailbox and nowhere else.
 *
 * @module core/mailbox
 */
import type { Storage } from '../storage/interface.ts';
import type { JSONValue } from './json.ts';
import type { ApplicationCommandAdmission, ApplicationCommandCancellationResult, ApplicationCommandCleanupResult, ApplicationCommandInput, ApplicationCommandReceipt, ApplicationCommandRejection, ApplicationCommandRenewalResult, ApplicationCommandSettleResult, MailboxCapacity, MailboxClaimResult, MailboxListOptions, MailboxMaintenanceReport, MailboxOptions, MailboxWaitOptions } from './mailbox-contract.ts';
/**
 * A durable, strictly FIFO application command mailbox.
 *
 * @example
 * ```ts
 * import { Mailbox, MemoryStorage } from '@lostgradient/weft';
 *
 * await using storage = new MemoryStorage();
 * using mailbox = new Mailbox({ storage, namespace: 'bureau', resourceId: 'agent-7' });
 *
 * const admission = await mailbox.admit({
 *   caller: 'user:42',
 *   target: 'agent:7',
 *   kind: 'steer',
 *   payload: { form: 'inline', value: { text: 'stop' } },
 *   idempotencyKey: 'steer-1',
 * });
 * console.log(admission.status); // 'admitted'
 *
 * const claimed = await mailbox.claim();
 * console.log(claimed.status); // 'claimed'
 * ```
 */
export declare class Mailbox {
    #private;
    constructor(options: MailboxOptions);
    /** The opaque application namespace this mailbox is scoped to. */
    get namespace(): string;
    /** The opaque resource identifier this mailbox is scoped to. */
    get resourceId(): string;
    /** The durable backend every transition compares and swaps against. */
    get storage(): Storage;
    /**
     * Offer a command to the mailbox.
     *
     * An exact retry of the same idempotency identity returns the original
     * receipt without creating a second command. Reusing the key with a different
     * caller, target, kind, or payload digest returns a conflict and leaves the
     * original command untouched. A full backlog is rejected before anything is
     * persisted.
     */
    admit(command: ApplicationCommandInput): Promise<ApplicationCommandAdmission>;
    /** Read one command's immutable receipt, or `null` when it is unknown or retired. */
    receipt(commandId: string): Promise<ApplicationCommandReceipt | null>;
    /**
     * List receipts in this mailbox, bounded and non-consuming.
     *
     * Listing never claims, starts, or advances work, so any number of observers
     * can call it concurrently without interfering with delivery.
     */
    list(options?: MailboxListOptions): Promise<ApplicationCommandReceipt[]>;
    /** Current backlog accounting. Deliberately low-cardinality: counts only. */
    capacity(): Promise<MailboxCapacity>;
    /**
     * Lease the FIFO head of this mailbox to one attempt.
     *
     * Strict FIFO is the contract: when the head is not due yet, `claim()` reports
     * `held` rather than skipping ahead to a later command. The returned claim
     * carries an attempt-scoped `AbortSignal` that fires on cancellation, lease
     * release, or mailbox disposal.
     */
    claim(options?: {
        readonly signal?: AbortSignal | undefined;
    }): Promise<MailboxClaimResult>;
    /** Extend a lease and report liveness for the current attempt. */
    renew(options: {
        readonly commandId: string;
        readonly attemptToken: string;
        readonly progress?: JSONValue | undefined;
    }): Promise<ApplicationCommandRenewalResult>;
    /** Settle a claimed command successfully. */
    acknowledge(options: {
        readonly commandId: string;
        readonly attemptToken: string;
        readonly outcome?: JSONValue | undefined;
    }): Promise<ApplicationCommandSettleResult>;
    /** Settle a claimed command as failed, optionally scheduling a retry. */
    reject(options: {
        readonly commandId: string;
        readonly attemptToken: string;
        readonly failure: ApplicationCommandRejection;
        readonly retry?: boolean | undefined;
    }): Promise<ApplicationCommandSettleResult>;
    /** Durably request cancellation and abort an in-process claimant. */
    requestCancellation(options: {
        readonly commandId: string;
        readonly reason?: string | undefined;
    }): Promise<ApplicationCommandCancellationResult>;
    /**
     * Read whether a cancelled command's claimant has finished. Non-consuming and
     * safe to call from any number of observers.
     */
    cleanupState(commandId: string): Promise<ApplicationCommandCleanupResult>;
    /**
     * Wait, bounded, for a cancelled command's claimant to settle.
     *
     * A `pending` result means this mailbox stopped waiting — never that the
     * handler stopped. A caller signal that aborts at any point — before a read,
     * during one, or during the sleep between polls — rejects the wait with that
     * signal's reason; disposing the mailbox during a read rejects with the
     * disposal error, and during a sleep returns the last observation. The
     * budget bounds the reads themselves as well as the sleeps between them: a
     * budget that runs out during a later read returns the last observation, and
     * one that runs out during the first read, with nothing observed yet,
     * rejects with `WaitBudgetElapsedError`.
     */
    awaitCleanup(options: {
        readonly commandId: string;
        readonly timeoutMs: number;
        readonly signal?: AbortSignal | undefined;
        readonly pollIntervalMs?: number | undefined;
    }): Promise<ApplicationCommandCleanupResult>;
    /**
     * Wait, bounded and abortably, until this mailbox has work due for delivery.
     *
     * Returns `true` when the FIFO head is claimable. Aborting, disposal, or the
     * timeout returns `false` and releases every process-local resource without
     * touching durable work.
     *
     * `timeoutMs` defaults to `0`, so calling this with no options checks once and
     * returns immediately rather than blocking. Pass a timeout to actually wait.
     */
    waitForAvailable(options?: MailboxWaitOptions): Promise<boolean>;
    /**
     * Run one bounded maintenance pass: release due commands, reclaim expired
     * leases at their original FIFO position, dead-letter commands past their
     * absolute deadline, and retire terminal receipts past retention.
     *
     * Nothing in this mailbox runs on a hidden timer, so a host configured with
     * `backgroundTasks: 'manual'` drives every time-based transition through this
     * one call.
     */
    runMaintenance(now?: number): Promise<MailboxMaintenanceReport>;
    /**
     * Release every process-local resource: abort in-flight waits and every
     * attempt-scoped signal this process holds.
     *
     * Disposal never deletes durable work. A claim this process held stays leased
     * until its visibility expires and maintenance reclaims it.
     */
    dispose(): void;
    /** `using`-compatible disposal. */
    [Symbol.dispose](): void;
}