/* Declarations for lib/gate.js — the module itself ships unchanged.

   The gate is what stops material being taught out of order. buildGate()
   computes it from curriculum + progress; renderGate() turns it into the
   {{GATE}} section of prompt/tutor-system.md. */

export interface Unit {
  id: string;
  ko: string;
  name: string;
  goal: string;
  vocabUnit: boolean;
  teaches: string[];
  avoid?: string[];
  /** Strictly NEW vocabulary. Deliberate repeats live in revisits[]. */
  words: string[];
  revisits?: { word: string; from: string }[];
}

/** A Unit with its phase stamped on, as flatten() returns it. */
export interface FlatUnit extends Unit {
  phase: number;
  phaseKo: string;
  phaseName: string;
}

export interface Phase {
  phase: number;
  ko: string;
  name: string;
  units: Unit[];
}

export interface Curriculum {
  version: number;
  note?: string;
  phases: Phase[];
}

export interface ProgressState {
  current: string;
  done: Record<string, boolean>;
  confidence?: Record<string, number>;
}

/**
 * Replaces the hand-listed word set with a dictionary query. Returning a
 * frequency band here is what turns 371 hand-typed words into something
 * that scales.
 */
export type VocabQuery = (unit: FlatUnit, done: FlatUnit[]) => string[];

export interface GateOptions {
  vocabQuery?: VocabQuery;
}

export interface Gate {
  unit: FlatUnit;
  phase: { n: number; ko: string; name: string };
  taught: string[];
  forbidden: { near: string[]; tailUnit: FlatUnit | null; count: number };
  vocabulary: string[];
  newWords: string[];
  /** Words met earlier that this unit should deliberately bring back. */
  revisits: string[];
  confidence: number | null;
  next: FlatUnit | null;
  finished: string[];
}

export function flatten(curriculum: Curriculum): FlatUnit[];

export function buildGate(
  curriculum: Curriculum,
  progress: ProgressState,
  opts?: GateOptions,
): Gate;

/** Render the gate into the system prompt section. Keep the headings. */
export function renderGate(g: Gate): string;