import type { ColdCode } from "../core/types.js";
import type { Versionage } from "../tables/table-types.js";
/** Attachment dispatch fallback is only defined for counter domains. */
export type AttachmentDispatchDomain = Extract<ColdCode, "txt" | "bny">;
/** Named presets for default attachment fallback strategy behavior. */
export type AttachmentDispatchMode = "strict" | "compat";
/** Structured info emitted when compat fallback crosses major versions. */
export interface VersionFallbackInfo {
    /** Version used for the failed primary dispatch attempt. */
    from: Versionage;
    /** Version selected for retry by compat policy. */
    to: Versionage;
    /** Parse domain where fallback occurred (`txt` qb64 or `bny` qb2). */
    domain: AttachmentDispatchDomain;
    /** Root parse failure message from the primary attempt. */
    reason: string;
}
/**
 * Policy decision for versioned attachment dispatch failure handling.
 *
 * `throw`:
 * - preserve strict fail-fast behavior.
 *
 * `retry`:
 * - perform one alternate-major retry and surface structured fallback info.
 */
export type VersionDispatchDecision = {
    action: "throw";
} | {
    action: "retry";
    retryVersion: Versionage;
    info: VersionFallbackInfo;
};
/**
 * Strategy interface for strict/compat dispatch fallback and wrapper recovery
 * semantics.
 */
export interface AttachmentVersionFallbackPolicy {
    /**
     * Decide whether a versioned dispatch failure should rethrow or retry.
     *
     * Why this exists:
     * keeps strict-vs-compat behavior out of parser control flow so policy can be
     * injected and validated independently.
     */
    onVersionDispatchFailure(error: Error, version: Versionage, domain: AttachmentDispatchDomain): VersionDispatchDecision;
    /**
     * Observe accepted fallback decisions (callback/telemetry/warning hook).
     *
     * Why this exists:
     * dispatch logic should not hardcode observability side effects.
     */
    onVersionFallback(info: VersionFallbackInfo): void;
    /**
     * Decide whether wrapper nested parse errors should preserve opaque remainder.
     *
     * Why this exists:
     * strict mode must fail on malformed wrapper tails; compat mode intentionally
     * keeps opaque remainder to preserve real-world stream tolerance.
     */
    shouldPreserveWrapperRemainder(error: Error): boolean;
}
/** Legacy strict/compat configuration inputs for policy construction. */
export interface AttachmentVersionFallbackPolicyOptions {
    /** Legacy strict/compat selector used only when no explicit policy is supplied. */
    mode?: AttachmentDispatchMode;
    /** Optional callback invoked when compat policy accepts a major-version retry. */
    onVersionFallback?: (info: VersionFallbackInfo) => void;
}
/**
 * Build default fallback strategy from legacy options.
 *
 * Why:
 * preserves backward-compatible `mode` API while allowing explicit policy
 * injection for new call sites.
 */
export declare function createAttachmentVersionFallbackPolicy(options?: AttachmentVersionFallbackPolicyOptions): AttachmentVersionFallbackPolicy;
//# sourceMappingURL=attachment-fallback-policy.d.ts.map