Dropped Events

How the mobile app surfaces frames the decoder refused, so a truncated answer is never reported as a clean success.

When the wire sends a frame the decoder cannot make sense of, the mobile app shows the refusal on the transcript instead of dropping it on the floor.

Quick Start

1. See a dropped row

   The composition root already wires the sink, so a dropped row appears on its own whenever a frame is malformed — nothing to enable.

   import { createApp } from "praisonai-mobile/app/boot";
   
   // createApp builds the DropSink and joins the engine to the controller.
   // A refused frame becomes a dropped row on the turn it arrived beside.
   const app = await createApp(deps);

How It Works

A refusal travels from the engine, through a small port, onto the transcript.

The engine and the controller cannot call each other — the engine is built at composition, the controller per app — so the DropSink is the seam between them.

export interface DropSink {
  note(reason: Dropped["reason"], detail: string): void;
  drain(): readonly Dropped[];
}

drain() empties the queue, so the same refusal is never repainted on a later event.

The Nine Rejection Reasons

Every refusal carries a machine tag and a user-facing sentence. Seven come from the decoder; two more come from parseFrame, which reads the raw frame before decoding.

The error-before-start Exception

An error that arrives before the turn began is not dropped — it becomes the turn’s outcome.

Every other event before start is a stray frame and drops as before_start. An error is the exception, because a failure before the first token — a 401, a 403, a 500, a refused connection, no network, a wrong baseUrl — is still this turn’s real outcome. apply() promotes the idle turn to streaming and reprocesses the error, so the true reason survives.

// transcript.ts — an error while idle is promoted, not dropped.
if (state.phase === "idle") {
  if (event.type === "error") {
    return apply({ ...state, phase: "streaming", msgId: event.msgId }, event);
  }
  return drop(state, "before_start", event.type); // everything else
}

Before this, every pre-first-token failure was dropped, then finish() re-labelled the empty turn kind: "empty" — so a 401 and a dead socket rendered identically as “the engine produced no output” plus a spurious dropped row. The auth → settings recovery branch never survived to the view.

The Three Drain Points

The controller drains the sink at three points, and each is load-bearing.

// After every event, so a refusal paints with the frame it arrived beside.
turn = apply(turn, event);
turn = drainDrops(turn);

// On every coalescer tick, so a stream where every frame is refused still
// paints refusals progressively rather than as one burst at the end.
turn = drainDrops(turn);
if (hadDrops) publish();

// In finally, so a refusal beside the LAST frame — or while the stream was
// dying — is still shown.
turn = drainDrops(turn);
turn = finish(turn);

The finally drain, not merely a catch drain, is what catches a last-frame refusal: the first version sat at the end of the catch and only ran when the turn had already failed.

The tick drain closes a distinct failure mode: when every frame is refused — a proxy answering a stream with HTML, say — nothing is ever yielded, so the per-event drain never runs. Before this, 60 refused frames/second for a minute arrived as one synchronous burst of ~3,600 appends and ~440 ms of blocked main thread on a phone, at the exact moment the app was trying to paint the failure. With the tick drain the worst single publish gap falls from ~110 ms to ~2 ms for the same 3,600 refusals.

Cross-Turn Behaviour

A refusal belongs to exactly one turn, and carry is what keeps one turn’s drops from staining the next.

// TurnState carries drops that arrived between turns, waiting for the next start.
readonly carry: readonly Dropped[];

apply(start) reads from state.carry — the drops noted while nothing was streaming — then clears it. It no longer carries the previous turn’s entire dropped list, which used to paint every later turn as damaged for the lifetime of the app.

Common Patterns

A dropped row is evidence, not noise. A stream that is 40% unparseable must be visible as a defect, so the count is worth reading.

if (turn.dropped.length > 0) {
  // The turn is not a clean success — some frames were refused.
  console.log(`${turn.dropped.length} refused`);
}

Anyone hand-constructing the engine must pass onIgnored, or refusals are invisible again.

import { createRemoteHttpEngine } from "praisonai-mobile/engines/remote-http";

const engine = createRemoteHttpEngine({
  baseUrl,
  http,
  onIgnored: (reason, detail) => sink.note(reason, detail),
});

Best Practices

Related