import { ChainId } from "../../model/primitives.js";
import "../../model/index.js";
//#region src/dev/mode-parity/fieldDiff.d.ts
/**
 * What kind of disagreement a {@link FieldDiff} describes, so that a reader can
 * bucket the report without re-deriving it from the values.
 *
 * - `"presence"` — one side has no value at all (`undefined` or `null`).
 * - `"usd"` — an {@link Amount.valueUsd}, i.e. a price-derived float.
 * - `"numeric"` — any other number or bigint.
 * - `"other"` — everything else: strings, booleans, array shapes.
 **/
export type DiffKind = "presence" | "usd" | "numeric" | "other";
/**
 * Why a {@link FieldDiff} is expected rather than a real disagreement.
 *
 * - `"mode-scoped"` — a field documented `@mode offchain` or `@mode onchain`,
 *   so the other source has nothing to put there.
 * - `"backend-preferred"` — both sources fill the field, but both-mode merge
 *   overlays the backend value.
 * - `"tolerance"` — snapshot lag or float-path noise within the thresholds
 *   below, not a formula or membership mismatch.
 **/
export type ExpectedDiffReason = "mode-scoped" | "backend-preferred" | "tolerance";
/**
 * One field of one row where the two sources disagree.
 **/
export interface FieldDiff {
  /**
   * Dotted path into the row, with array elements keyed by their own identity
   * rather than by index, e.g. `allowedDepositTokens[0xa0b8...].symbol`.
   **/
  path: string;
  /**
   * Value the chain reported, `undefined` when it has no such field.
   **/
  onchain: unknown;
  /**
   * Value the backend reported, see {@link onchain}.
   **/
  offchain: unknown;
  kind: DiffKind;
  /**
   * Present when this disagreement is documented or within snapshot-lag noise,
   * so it does not keep the row from being counted as similar.
   **/
  expected?: true;
  reason?: ExpectedDiffReason;
}
/**
 * The largest numeric disagreement seen for one collapsed field path, on
 * either the unexpected or the expected side.
 **/
export interface WorstDiff {
  /**
   * Entity id (position/opportunity id) with the biggest relative difference.
   **/
  id: string;
  /**
   * Uncollapsed path, so the exact array element is named.
   **/
  path: string;
  /**
   * Relative difference in bps.
   **/
  bps: number;
  onchain: unknown;
  offchain: unknown;
}
/**
 * One field disagreement together with the matched row it belongs to.
 **/
export interface EntityFieldDiff {
  id: string;
  diff: FieldDiff;
}
/**
 * How often one field disagreed across all matched rows, with array keys
 * collapsed, e.g. `allowedDepositTokens[].symbol`.
 **/
export interface DiffPathCount {
  path: string;
  kinds: DiffKind[];
  count: number;
  expected: number;
  unexpected: number;
  /**
   * Largest unexpected numeric disagreement, when any unexpected diff of this
   * path yields a relative bps value.
   **/
  worstUnexpected?: WorstDiff;
  /**
   * Largest expected numeric disagreement, see {@link worstUnexpected}.
   **/
  worstExpected?: WorstDiff;
}
/**
 * Counts of one chain, one wallet, or of the whole report when those ids are
 * absent.
 **/
export interface CompareCounts {
  onchainRows: number;
  offchainRows: number;
  matched: number;
  /**
   * Matched rows with no unexpected diffs.
   **/
  similar: number;
  /**
   * Matched rows with at least one unexpected diff.
   **/
  different: number;
  onlyOnchain: number;
  onlyOffchain: number;
}
/**
 * Counts of one chain.
 **/
export interface ChainCompareCounts extends CompareCounts {
  chainId: ChainId;
}
/**
 * Identity of an array element, used so a token present on one side only is
 * reported as such rather than shifting every later element into a diff.
 *
 * Return a string to key the element; `undefined` falls back to the default
 * (`address`, `id`, `token`, or nested `token.address`).
 **/
export type ArrayElementKey = (path: string, value: unknown) => string | undefined;
/**
 * How to walk two values. Callers that need identity-bearing arrays whose
 * key is not one of the defaults pass {@link DiffOptions.keyOf}.
 **/
export interface DiffOptions {
  keyOf?: ArrayElementKey;
}
/**
 * Relative drift allowed on {@link Amount.valueUsd} before a USD float is a
 * real disagreement: 0.1%.
 **/
export declare const USD_RELATIVE_EPSILON = 0.001;
/**
 * Relative drift allowed on lag-bounded bigint amounts: 0.05%.
 **/
export declare const AMOUNT_RELATIVE_EPSILON = 0.0005;
/**
 * Absolute drift allowed on bps rates before rounding and a one-block lag are
 * no longer enough to explain it.
 **/
export declare const BPS_ABSOLUTE_EPSILON = 1;
/**
 * Every field two versions of one value disagree on. Nothing is filtered or
 * tagged: the caller marks expected diffs afterwards.
 **/
export declare function diffValue(path: string, onchain: unknown, offchain: unknown, out: FieldDiff[], options?: DiffOptions): void;
/**
 * Deep-diff two values and return the disagreements, in path order of
 * discovery.
 **/
export declare function diffObjects(onchain: unknown, offchain: unknown, options?: DiffOptions): FieldDiff[];
/**
 * Mark a diff expected, so a later `similar` count can ignore it.
 **/
export declare function withExpected(diff: FieldDiff, reason: ExpectedDiffReason): FieldDiff;
/**
 * How often each field differed, with array keys collapsed so that the same
 * field of a hundred collateral tokens counts as one path. Sorted so the
 * unexpected disagreements come first.
 **/
export declare function countPaths(diffs: Iterable<EntityFieldDiff>): DiffPathCount[];
/**
 * Collapse `allowedDepositTokens[0xa0b8...].symbol` to `allowedDepositTokens[].symbol`.
 **/
export declare function collapseArrayKeys(path: string): string;
/**
 * Membership and match totals of one comparison, from already-built lists.
 **/
export declare function toCompareCounts(onchainRows: number, offchainRows: number, onlyOnchain: number, onlyOffchain: number, matched: ReadonlyArray<{
  similar: boolean;
}>): CompareCounts;
/**
 * USD floats within {@link USD_RELATIVE_EPSILON}.
 **/
export declare function isUsdWithinTolerance(onchain: unknown, offchain: unknown): boolean;
/**
 * Bps rates that differ by at most {@link BPS_ABSOLUTE_EPSILON}.
 **/
export declare function isBpsWithinTolerance(onchain: unknown, offchain: unknown): boolean;
/**
 * Bigint amounts within {@link AMOUNT_RELATIVE_EPSILON}.
 **/
export declare function isAmountWithinTolerance(onchain: unknown, offchain: unknown): boolean;
/**
 * Finite numbers within a relative epsilon of each other.
 **/
export declare function withinRelative(onchain: number | undefined, offchain: number | undefined, epsilon: number): boolean;
/**
 * `diff / max(|a|, |b|) <= epsilon`, computed in integer arithmetic so a
 * 1e18-scale amount does not round through `Number`.
 **/
export declare function withinRelativeBigint(onchain: bigint, offchain: bigint, epsilon: number): boolean;
export declare function asFiniteNumber(value: unknown): number | undefined;
/**
 * Relative difference of two numbers or bigints, in bps:
 * `|a − b| / max(|a|, |b|) * 10_000`. `undefined` when the values are not
 * a comparable pair of finite numbers or of bigints.
 **/
export declare function relativeDiffBps(onchain: unknown, offchain: unknown): number | undefined;
export declare function union(left: string[], right: string[]): string[];
export declare function isRecord(value: unknown): value is Record<string, unknown>;
//#endregion