/**
 * WO-2 Pipeline 1, T3 — Amazon Transcribe Streaming bridge.
 *
 * Takes the in-process PCM buffer T2 accumulated (an AudioSession's
 * drained Float32Array) and streams it to Amazon Transcribe Streaming over
 * the AWS SDK's HTTP/2 connection. Emits partial results as they arrive
 * (drives EVE's "processing" micro-expression) and the final result once
 * Transcribe settles on stable text.
 *
 * Credentials: retrieved via the AMANDA vault MCP (`get_key("aws")`) at
 * call time, never hardcoded, never read from a committed .env value.
 */

/**
 * Converts a Float32Array of PCM samples in [-1, 1] into the 16-bit signed
 * little-endian PCM bytes Transcribe Streaming expects for `MediaEncoding:
 * 'pcm'`. Clamps out-of-range samples rather than wrapping, since a wrapped
 * sample is audibly worse (a loud click) than a clamped one (brief clipping).
 */
export function float32ToPcm16(samples) {
  const out = Buffer.alloc(samples.length * 2);
  for (let i = 0; i < samples.length; i++) {
    const clamped = Math.max(-1, Math.min(1, samples[i]));
    const intSample = Math.round(clamped * 32767);
    out.writeInt16LE(intSample, i * 2);
  }
  return out;
}

/**
 * Wraps a single Float32Array buffer as the one-shot AsyncIterable the AWS
 * SDK's `AudioStream` parameter expects. Real streaming (many chunks over
 * time) would yield multiple times; T2's current buffering model hands us
 * one complete utterance at speech-end, so one yield is correct here.
 */
async function* singleChunkAudioStream(pcm16) {
  yield { AudioEvent: { AudioChunk: pcm16 } };
}

/**
 * Runs one Transcribe Streaming session against a single buffered
 * utterance. Calls `onPartial(text)` for every `IsPartial: true` result and
 * resolves with the final stable transcript once received.
 *
 * `clientFactory` and `commandFactory` are injectable so tests can supply a
 * mock without needing real AWS credentials or network access — the
 * production caller (see wireAudioPipeline in run.mjs, T4) passes the real
 * AWS SDK classes.
 */
export async function transcribeUtterance({
  samples,
  sampleRateHz,
  onPartial,
  TranscribeStreamingClient,
  StartStreamTranscriptionCommand,
  clientConfig,
}) {
  if (samples.length === 0) {
    return { text: "", partialCount: 0 };
  }

  const client = new TranscribeStreamingClient(clientConfig ?? { region: "us-east-1" });
  const pcm16 = float32ToPcm16(samples);

  const command = new StartStreamTranscriptionCommand({
    LanguageCode: "en-US",
    MediaSampleRateHertz: sampleRateHz,
    MediaEncoding: "pcm",
    AudioStream: singleChunkAudioStream(pcm16),
    EnablePartialResultsStabilization: true,
    PartialResultsStability: "medium",
  });

  const response = await client.send(command);
  let finalText = "";
  let partialCount = 0;

  for await (const event of response.TranscriptResultStream ?? []) {
    const results = event.TranscriptEvent?.Transcript?.Results ?? [];
    for (const result of results) {
      const text = result.Alternatives?.[0]?.Transcript ?? "";
      if (result.IsPartial) {
        partialCount += 1;
        onPartial?.(text);
      } else {
        finalText = text;
      }
    }
  }

  return { text: finalText, partialCount };
}

/**
 * Per-connection re-entrancy guard: WO-2 REQ says a new speech-start while
 * a Transcribe stream is active for that session must close the current
 * stream gracefully and open a new one, not silently interleave two.
 *
 * Since `transcribeUtterance` above is a single-shot call over one
 * complete buffered utterance (not a genuinely long-lived stream), "close
 * gracefully" here means: abandon interest in the in-flight call's result
 * rather than awaiting/broadcasting it, and let a new call start
 * immediately. `TranscribeSessionGuard` tracks an increasing generation
 * number per session id so a stale in-flight call's result is detected and
 * dropped instead of racing a newer one to the broadcast.
 */
export class TranscribeSessionGuard {
  constructor() {
    /** @type {Map<string, number>} sessionId -> current generation */
    this.generations = new Map();
  }

  /** Call when starting a new utterance for this session; returns a token
   * to check against later. */
  begin(sessionId) {
    const next = (this.generations.get(sessionId) ?? 0) + 1;
    this.generations.set(sessionId, next);
    return next;
  }

  /** True if `token` is still the most recent generation for this session
   * — i.e. no newer speech-start has superseded this call. */
  isCurrent(sessionId, token) {
    return this.generations.get(sessionId) === token;
  }
}