/** One data-boundary request that FAILED during capture — an embedded fallback branch. */
export type DataResidueEntry = {
    /**
     * Stable identity across captures: `<surface>·<endpoint>` where `endpoint` is the
     * request URL's `pathname` (query stripped so `?all=1` vs `?all=2` don't fork the
     * key). Escaped so it can't inject Markdown into the report/PR-comment summary.
     */
    key: string;
    /** The captured surface key this failure was observed on. */
    surface: string;
    /** The failing endpoint's URL pathname (query stripped). */
    endpoint: string;
    /** Why it failed: a network error text (`net::ERR_CONNECTION_REFUSED`) or `HTTP 503`. */
    reason: string;
};
/** `key -> reason` — failing endpoints that are intentional/known and on the record. */
export type AcknowledgedResidue = Record<string, string>;
/** Acknowledgement file, parallel to the inventory guard's `styleproof.inventory.json`. */
export declare const DATA_RESIDUE_ACK_FILE = "styleproof.data-residue.json";
/**
 * Read the acknowledged-residue file (`$STYLEPROOF_DATA_RESIDUE` or
 * `styleproof.data-residue.json`). `{}` when absent; THROWS on malformed JSON — the
 * caller picks the policy (the CI gate fails loud so a broken ack file can't silently
 * un-acknowledge a real failure; the advisory report degrades to `{}`). Mirrors
 * `readAckFile` in the inventory guard exactly.
 */
export declare function readResidueAckFile(): AcknowledgedResidue;
/** Build a residue key from a surface and an endpoint URL. Query stripped, escaped. */
export declare function residueKey(surface: string, endpoint: string): string;
/** The endpoint pathname a URL resolves to, query stripped. Falls back to the raw URL. */
export declare function endpointOf(url: string): string;
/**
 * Union the per-surface `map.dataResidue` of a whole run into one deduped set, keyed by
 * `key` (surface·endpoint), so the same failure seen across widths / a self-check re-run
 * is ONE entry, not a spray. Sorted for a stable rendering order.
 */
export declare function unionResidue(perSurface: Array<{
    dataResidue?: DataResidueEntry[];
} | undefined>): DataResidueEntry[];
export type ResidueAudit = {
    /** Every failing endpoint observed across the run (union, deduped). */
    residue: DataResidueEntry[];
    /** Failing endpoints NOT acknowledged in the ledger — the gate fails on a non-empty set. */
    unacknowledged: DataResidueEntry[];
    /** Acknowledged keys no longer present in the residue (the endpoint is fixtured/gone) —
     *  a rotted opt-out, so the ledger can't quietly rot (mirrors the `exclude` guard). */
    staleAcknowledgements: string[];
};
/**
 * The gate. A failing endpoint whose key isn't in `acknowledged` (key -> reason) is
 * unacknowledged — the caller fails on a non-empty result. An `acknowledged` key that
 * isn't actually failing is stale, returned separately so the ledger can't rot. Unlike
 * the inventory guard (a base-vs-head REMOVAL), residue is present-on-HEAD: the head
 * capture's failing endpoints are audited directly, so only the head maps matter.
 */
export declare function auditResidue(headMaps: Array<{
    dataResidue?: DataResidueEntry[];
} | undefined>, acknowledged?: AcknowledgedResidue): ResidueAudit;
/**
 * Run-level entry point for a gate/report: audit the HEAD bundle's residue against the
 * acknowledgement ledger, carrying whether the guard was ARMED to gate. `armed` comes
 * from the head coverage ledger's `dataResidue: 'gate'` (the default; only an explicit
 * `'warn'` — or an older bundle with no field — is unarmed). When not armed, the caller
 * still surfaces residue (warn is the explicit opt-out) but must not block.
 */
export declare function auditRunResidue(headMaps: Array<{
    dataResidue?: DataResidueEntry[];
} | undefined>, acknowledged: AcknowledgedResidue, armed: boolean): ResidueAudit & {
    armed: boolean;
};