dyolink/backend/src/modules/voice/tooth-intent.resolver.ts

import {
  isFdiTooth,
  normalizeFdiCode,
  toFdi,
  type Arch,
  type PatientSide,
} from '../../common/fdi';
import type { ToothIntent, UnresolvedItem } from './voice.types';

const ARCHES: readonly Arch[] = ['upper', 'lower'];
const SIDES: readonly PatientSide[] = ['patient_right', 'patient_left'];

export type ToothResolution = {
  /** Unique FDI codes, sorted (matching normalizeTeeth's ordering). */
  teeth: string[];
  unresolved: UnresolvedItem[];
};

/** Everything here parses untrusted model output, so nothing may throw. */
function normalizedFdi(intent: ToothIntent): string {
  // Same normalisation the wire layer used to pick this branch, so the two cannot
  // disagree: '14 ' is tooth 14 through the treatment API and '۲۶' is tooth 26, and
  // neither may be reported as malformed here.
  return normalizeFdiCode((intent as { fdi?: unknown }).fdi);
}

/**
 * Resolve one spoken tooth reference to an FDI code, or null.
 *
 * Never guesses and never clamps: a position of 9, a deciduous tooth, or a malformed
 * intent resolves to null so the caller can surface it as "not understood" rather than
 * silently selecting a neighbouring tooth.
 */
export function resolveToothIntent(intent: ToothIntent): string | null {
  if (!intent || typeof intent !== 'object') return null;

  if (intent.kind === 'explicit') {
    const fdi = normalizedFdi(intent);
    return isFdiTooth(fdi) ? fdi : null;
  }

  if (intent.kind === 'positional') {
    if (intent.arch !== 'upper' && intent.arch !== 'lower') return null;
    if (intent.side !== 'patient_right' && intent.side !== 'patient_left')
      return null;
    return toFdi(intent.arch, intent.side, intent.position);
  }

  return null;
}

function unresolvedReason(intent: ToothIntent): UnresolvedItem['reason'] {
  if (!intent || typeof intent !== 'object') return 'malformed';

  if (intent.kind === 'explicit') {
    const fdi = normalizedFdi(intent);
    // Quadrants 1-4 are permanent and would already have resolved, so a well-formed
    // quadrant+position reaching here is quadrant 5-8: deciduous. Anything else is noise.
    return /^[1-8][1-8]$/.test(fdi) ? 'not_permanent_tooth' : 'malformed';
  }

  if (intent.kind === 'positional') {
    const positionBad =
      !Number.isInteger(intent.position) ||
      intent.position < 1 ||
      intent.position > 8;
    if (positionBad) return 'position_out_of_range';
    // The position was understood, so the words were not the problem: the speaker never
    // said which quadrant. "دندون دو" names four teeth at once, and telling the
    // clinician it "could not be read" would send them looking for the wrong fault.
    const archMissing = intent.arch !== 'upper' && intent.arch !== 'lower';
    const sideMissing =
      intent.side !== 'patient_right' && intent.side !== 'patient_left';
    return archMissing || sideMissing ? 'tooth_missing_quadrant' : 'malformed';
  }

  return 'malformed';
}

/**
 * The teeth still consistent with what *was* heard.
 *
 * Narrowed by whatever the clinician did say, so "دو" offers four and "دو بالا" offers
 * two. This is not a guess — it is the full set of readings, handed to the clinician to
 * choose from rather than picked on their behalf.
 */
function quadrantCandidates(intent: ToothIntent): string[] {
  if (intent.kind !== 'positional') return [];
  const arches =
    intent.arch === 'upper' || intent.arch === 'lower' ? [intent.arch] : ARCHES;
  const sides =
    intent.side === 'patient_right' || intent.side === 'patient_left'
      ? [intent.side]
      : SIDES;

  const codes: string[] = [];
  for (const arch of arches) {
    for (const side of sides) {
      const fdi = toFdi(arch, side, intent.position);
      if (fdi) codes.push(fdi);
    }
  }
  return codes.sort();
}

function spokenOf(intent: ToothIntent): string {
  const spoken = (intent as { spoken?: unknown })?.spoken;
  return typeof spoken === 'string' && spoken.trim() ? spoken.trim() : '';
}

/**
 * Resolve a list of spoken tooth references.
 *
 * Duplicates collapse — a clinician may name the same tooth twice in one sentence — and
 * anything unresolvable is reported rather than dropped, so the review sheet can show the
 * user exactly which words were not understood.
 */
export function resolveToothIntents(
  intents: readonly ToothIntent[],
): ToothResolution {
  const teeth = new Set<string>();
  const unresolved: UnresolvedItem[] = [];
  const seenUnresolved = new Set<string>();

  // Not `intents ?? []`: a model may return an object or a number here, and a
  // non-iterable must degrade like any other malformed shape rather than throw.
  const list: readonly ToothIntent[] = Array.isArray(intents)
    ? (intents as readonly ToothIntent[])
    : [];

  for (const intent of list) {
    const fdi = resolveToothIntent(intent);
    if (fdi) {
      teeth.add(fdi);
      continue;
    }
    const reason = unresolvedReason(intent);
    const spoken = spokenOf(intent);
    const candidates =
      reason === 'tooth_missing_quadrant' ? quadrantCandidates(intent) : [];
    // Only dedupe items we can actually tell apart. Without `spoken`, two distinct lost
    // references would collapse into one blank review row and a tooth would vanish. The
    // candidates are part of the identity: the same word with a different arch heard
    // offers a different choice.
    if (spoken) {
      const key = `${spoken}::${reason}::${candidates.join(',')}`;
      if (seenUnresolved.has(key)) continue;
      seenUnresolved.add(key);
    }
    unresolved.push(
      candidates.length > 0
        ? { spoken, reason, candidates }
        : { spoken, reason },
    );
  }

  return { teeth: [...teeth].sort(), unresolved };
}