/**
 * `@variance-authority/wire/listen` — the driver's end of the medium.
 *
 * One listener per driver process, and one address per execution. The execution
 * is in the address rather than in the body, so a participant repeats nothing it
 * was told and the driver reads back the key it minted itself: a report cannot
 * claim an execution by writing one down.
 *
 * The same object is also the carrier for realms the driver is inside
 * ({@link Wire.carrier}) — a page it exposes a function to, a server it started
 * in-process. Those never touch the socket, and nothing above here knows which
 * of the two a report came in on.
 *
 * Loopback, because that is the whole of the reach this needs: a suite and the
 * services it drives are on one machine, which is what the cookie already
 * assumes by being same-origin. The port is ephemeral, so nothing is agreed in
 * advance and several workers listen at once without a word between them.
 */
import type { Participant, WireCarrier } from './index.js';
/** The function a driver exposes in a page for the page's carrier to call. */
export declare const WIRE_REPORT = "__VAW_REPORT__";
/** What a driver does with one report. */
export type WireHandler = (journey: string | undefined, body: unknown) => void;
/** A listening driver. */
export interface Wire {
    /** Where this listener is, with no execution in it yet. */
    readonly origin: string;
    /** Where a participant answering for `journey` should report. */
    readonly addressFor: (journey: string) => string;
    /** The same desk, for a realm this driver is inside rather than talking to. */
    readonly carrier: WireCarrier;
    /** Take one instrument's reports until the returned call gives them up. */
    readonly on: (participant: Participant, handler: WireHandler) => () => void;
    readonly close: () => Promise<void>;
}
export interface ListenOptions {
    /**
     * The interface to listen on. Defaults to `127.0.0.1`, which is what a
     * participant is willing to answer; anything else is refused there rather
     * than here.
     */
    readonly host?: string;
    /**
     * What a reader gets when it asks this listener a question, if anything.
     *
     * Opt-in, and absent everywhere but a watcher. A listener is a place
     * participants report *to*, and a driver that holds its reports in memory
     * nobody else may see is the normal case: heads and event collectors pass
     * nothing here and keep answering `404` to every read, exactly as they did
     * before this existed.
     *
     * The one caller that does pass it has a second audience — an agent asking
     * about a run in flight — and no other way to reach it, because the memory
     * being asked about ends with the process holding it. Returning `undefined`
     * declines a path, so the reader's surface is the handler's to define rather
     * than this module's.
     */
    readonly answer?: (path: string) => unknown;
}
/**
 * Start taking what participants report.
 *
 * A body this reader cannot parse is dropped and answered as a refusal, so a
 * participant that acknowledges its reports learns it lost one. Throwing here
 * instead would take the run out on the observer's behalf, which is the one
 * thing this side may never do.
 */
export declare function listen(options?: ListenOptions): Promise<Wire>;
/**
 * Put a carrier in this process, for a subject the driver is running inside.
 *
 * The returned call gives the global back. Same shape as the page's carrier and
 * the same reports arrive, which is the point: a suite that starts its server
 * in-process configures nothing and loses nothing.
 */
export declare function installCarrier(carrier: WireCarrier): () => void;
/**
 * Source that installs the page's carrier, for a driver to evaluate before
 * navigation.
 *
 * A string because it has to run before the application does, in a realm with no
 * module graph yet. The exposed channel is read at report time rather than
 * captured at install time, so the two halves may be installed in either order,
 * and anything said before the channel exists is held rather than dropped — the
 * first decision of the first script is exactly the one a test most wants.
 *
 * The id comes off the document's own cookie, so a page reports under the same
 * execution a service behind it reports under.
 */
export declare function wireCarrierSource(): string;
//# sourceMappingURL=listen.d.ts.map