Types

interface ClaimMap {
  // ── Shape of the relationship ─────────────────────────────────────────────

  /** Direction and rate of a straight-line relationship. */
  "trend.linear": {
    direction: "rising" | "falling" | "flat";
    /** Change in Y per one-unit increase in X. */
    slope: number;
    intercept: number;
  };

  /** Shape of a fitted polynomial curve. */
  "trend.polynomial": {
    degree: number;
    leadingCoefficient: number;
    shape: "line" | "parabola-up" | "parabola-down" | "cubic" | "higher-order";
    /** X position of the extremum. Quadratics only; `null` otherwise. */
    vertexX: number | null;
    equation: string;
  };

  /** Growth regime of a fitted power law, y = a·x^b. */
  "trend.power": {
    /** The exponent b. */
    exponent: number;
    /** The scale coefficient a — the predicted Y at x = 1. */
    scale: number;
    regime: "superlinear" | "proportional" | "sublinear" | "flat" | "inverse";
    /** Y is multiplied by this when X doubles: 2^b. */
    doublingFactor: number;
    equation: string;
  };

  /** Constant proportional growth or decay, y = a·e^(bx). */
  "trend.exponential": {
    /** The growth rate b. */
    rate: number;
    /** The initial value a — the predicted Y at x = 0. */
    initial: number;
    direction: "growth" | "decay" | "flat";
    /** Y is multiplied by this for each unit step in X: e^b. */
    perStepFactor:
// …truncated

interface LinearFactOptions extends CommonFactOptions {
  /** p-value below which the slope is called significant. @default 0.05 */
  significanceLevel?: number;
}

interface LogisticFactOptions {
  /** Accuracy below this emits a caveat. @default 0.7 */
  accuracyWarningThreshold?: number;
  /** McFadden pseudo-R² at or above which the fit is "moderate". @default 0.2 */
  pseudoR2ThresholdWeak?: number;
  /** McFadden pseudo-R² at or above which the fit is "strong". @default 0.4 */
  pseudoR2ThresholdStrong?: number;
  smallSampleThreshold?: number;
}

interface PolynomialFactOptions extends CommonFactOptions {
  /** degree/n above which an overfit caveat fires. @default 0.33 */
  overfitRatioThreshold?: number;
}

interface PowerFactOptions extends CommonFactOptions {
  /** |b − 1| below this counts as proportional. @default 0.1 */
  nearLinearThreshold?: number;
}

interface Provenance {
  method: RegressionMethod;
  /** Observations the fit was computed from. */
  n: number;
  /**
   * The configuration that turned raw numbers into a qualifier — the R²
   * thresholds behind `"strong"`, the sample-size threshold behind a caveat.
   * Present only where a judgement was made.
   */
  basis?: Readonly<Record<string, number>>;
}

type Annotation =
  | (AnnotationBase & {
      kind: "curve";
      role: "fit";
      /** Predicted points spanning the observed domain. */
      points: readonly PredictedPoint[];
      /**
       * The `[min, max]` X span `points` covers.
       *
       * Lets a consumer tell observed from extrapolated without scanning, and
       * gives it a starting point for extending the curve past the data.
       */
      domain: readonly [number, number];
    })
  | (AnnotationBase & {
      kind: "band";
      /**
       * `"confidence"` bounds the fitted line itself; `"prediction"` bounds a
       * single future observation and is always wider.
       */
      role: "confidence" | "prediction";
      /** Bounds at each x, in ascending x order. */
      points: readonly { x: number; lower: number; upper: number }[];
      /** The confidence level the bounds were computed at, e.g. `0.95`. */
      level: number;
    })
  | (AnnotationBase & {
      kind: "marker";
      role: "vertex" | "decision-boundary";
      /** Position on the X axis. */
      x: number;
    });

type ClaimOf<K extends FactKind> = ClaimMap[K];

type Fact<K extends FactKind = FactKind> = K extends FactKind
  ? {
      /** The vocabulary of everything statili can assert. */
      kind: K;
      /** Structured, narrowed by `kind`. Never prose. */
      claim: ClaimOf<K>;
      /** Is this notable, notably absent, or a caveat on another fact? */
      level: FactLevel;
      /** Everything needed to audit or reproduce the claim. */
      provenance: Provenance;
      /** Structured, not `"drawTrendLine:1.2,0.4"`. */
      annotations?: Annotation[];
    }
  : never;

type FactKind = keyof ClaimMap;

type FactLevel = "finding" | "no-finding" | "caveat";

type FactResult = FactResultSuccess | FactResultError;

type FactResultError = {
  ok: false;
  /** End-user facing, not developer facing. */
  message: string;
  helpText: string;
  originalErrorType: string;
};

type FactResultSuccess = {
  ok: true;
  facts: Fact[];
};

type LogarithmicFactOptions = CommonFactOptions;

type MultilinearFactOptions = CommonFactOptions;

type RegressionMethod =
  | "linear"
  | "logarithmic"
  | "exponential"
  | "power"
  | "polynomial"
  | "multilinear"
  | "logistic"
  /** Not a regression — a smoother. Named here because provenance covers both. */
  | "loess";