DEV Community: LunarDrift

Stop Snapshot-Testing Voice Conversations: Verify the Turn Protocol Instead

LunarDrift — Sun, 25 Oct 2026 17:08:59 +0000

A real-time voice companion can behave correctly while its test suite reports failure.

The usual culprit is not that “the LLM knows better.” It is that the test encoded an assumption the product never promised: an exact sentence, a fixed callback order, or playback beginning within an arbitrary sleep interval.

That creates an uncomfortable engineering tension. You do not want to dismiss failures as harmless AI variability, but you also do not want brittle tests blocking valid behavior.

A better approach is to test the conversation protocol deterministically and evaluate the conversation content separately. For a Tencent RTC conversational AI application, that means verifying facts such as:

User speech invalidates the previous turn.
An interrupted response cannot resume later.
Stale ASR, LLM, or playback callbacks cannot take control of the session.
A timeout produces visible recovery instead of indefinite silence.
Every asynchronous result remains correlated with its originating turn and request.

We will build that test oracle in TypeScript, reproduce the dangerous races, and then map it onto the live voice pipeline.

Start with the disputed failure

Consider this test:

expect(answer).toBe("Your meeting begins at 3 PM.");

The model returns:

The meeting starts at 3 PM.

The assertion failed, but that alone does not establish a product defect. The test mixed three different questions:

Protocol: Did the response belong to the current user turn?
Policy: Was the assistant permitted to answer?
Content: Was the answer sufficiently correct and useful?

Only the last question involves linguistic variability. The first two should remain deterministic.

The human decision is therefore not “trust the model or trust the test.” It is: which product contract was this test supposed to enforce?

Draw the asynchronous boundary

A production voice companion is not one AI call. Keep these responsibilities separate:

Microphone / RTC media
        ↓
Speech recognition
        ↓
Application turn coordinator
        ↓
LLM
        ↓
Speech synthesis
        ↓
RTC playback

The application coordinator owns the current turn. Neither a late model response nor a delayed playback callback gets to decide that it is still relevant.

Tencent RTC documents Conversational AI as a real-time voice interaction scenario that can connect users with multiple LLM providers. Its LLM configuration guidance also covers OpenAI-compatible models and request identifiers used for routing and observability:

The event and effect names below belong to our application. They are not Tencent RTC SDK method names.

Create the reproducible project

mkdir voice-protocol-oracle
cd voice-protocol-oracle
npm init -y
npm install --save-dev typescript vitest tsx @types/node
npm pkg set type=module
npm pkg set scripts.test="vitest run"
mkdir src

Create src/session.ts:

export type Phase =
  | "idle"
  | "userSpeaking"
  | "transcribing"
  | "thinking"
  | "preparingAudio"
  | "speaking"
  | "recovery"
  | "offline";

export type State = {
  phase: Phase;
  turn: number;
  requestId?: string;
};

export type Event =
  | { type: "USER_STARTED" }
  | { type: "USER_ENDED" }
  | {
      type: "TRANSCRIPT_READY";
      turn: number;
      requestId: string;
      text: string;
    }
  | { type: "TRANSCRIPT_FAILED"; turn: number }
  | {
      type: "MODEL_DONE";
      turn: number;
      requestId: string;
      text: string;
    }
  | { type: "MODEL_TIMEOUT"; turn: number; requestId: string }
  | { type: "PLAYBACK_STARTED"; turn: number; requestId: string }
  | { type: "PLAYBACK_ENDED"; turn: number; requestId: string }
  | { type: "PLAYBACK_FAILED"; turn: number; requestId: string }
  | { type: "DISCONNECTED" };

export type Effect =
  | { type: "REQUEST_TRANSCRIPT"; turn: number }
  | {
      type: "REQUEST_MODEL";
      turn: number;
      requestId: string;
      text: string;
    }
  | {
      type: "SPEAK";
      turn: number;
      requestId: string;
      text: string;
    }
  | { type: "CANCEL_AUDIO"; turn: number; requestId: string }
  | { type: "NOTICE"; message: string }
  | { type: "LOG_STALE"; source: string; turn: number; requestId?: string };

export const initialState: State = {
  phase: "idle",
  turn: 0,
};

function isCurrent(
  state: State,
  turn: number,
  requestId?: string,
): boolean {
  return (
    state.turn === turn &&
    (requestId === undefined || state.requestId === requestId)
  );
}

function stale(
  state: State,
  source: string,
  turn: number,
  requestId?: string,
): [State, Effect[]] {
  return [
    state,
    [{ type: "LOG_STALE", source, turn, requestId }],
  ];
}

export function reduce(
  state: State,
  event: Event,
): [State, Effect[]] {
  switch (event.type) {
    case "USER_STARTED": {
      if (state.phase === "userSpeaking") return [state, []];

      const effects: Effect[] = [];

      if (
        (state.phase === "preparingAudio" || state.phase === "speaking") &&
        state.requestId
      ) {
        effects.push({
          type: "CANCEL_AUDIO",
          turn: state.turn,
          requestId: state.requestId,
        });
      }

      return [
        {
          phase: "userSpeaking",
          turn: state.turn + 1,
        },
        effects,
      ];
    }

    case "USER_ENDED": {
      if (state.phase !== "userSpeaking") return [state, []];

      return [
        { ...state, phase: "transcribing" },
        [{ type: "REQUEST_TRANSCRIPT", turn: state.turn }],
      ];
    }

    case "TRANSCRIPT_READY": {
      if (
        state.phase !== "transcribing" ||
        !isCurrent(state, event.turn)
      ) {
        return stale(state, "transcript", event.turn, event.requestId);
      }

      if (!event.text.trim()) {
        return [
          { ...state, phase: "recovery" },
          [{ type: "NOTICE", message: "I did not catch that. Please try again." }],
        ];
      }

      return [
        {
          ...state,
          phase: "thinking",
          requestId: event.requestId,
        },
        [
          {
            type: "REQUEST_MODEL",
            turn: event.turn,
            requestId: event.requestId,
            text: event.text,
          },
        ],
      ];
    }

    case "TRANSCRIPT_FAILED": {
      if (state.phase !== "transcribing" || !isCurrent(state, event.turn)) {
        return stale(state, "transcript-error", event.turn);
      }

      return [
        { ...state, phase: "recovery" },
        [{ type: "NOTICE", message: "Speech recognition is unavailable. Try again." }],
      ];
    }

    case "MODEL_DONE": {
      if (
        state.phase !== "thinking" ||
        !isCurrent(state, event.turn, event.requestId)
      ) {
        return stale(state, "model", event.turn, event.requestId);
      }

      if (!event.text.trim()) {
        return [
          { ...state, phase: "recovery" },
          [{ type: "NOTICE", message: "No answer was produced. Please retry." }],
        ];
      }

      return [
        { ...state, phase: "preparingAudio" },
        [
          {
            type: "SPEAK",
            turn: event.turn,
            requestId: event.requestId,
            text: event.text,
          },
        ],
      ];
    }

    case "MODEL_TIMEOUT": {
      if (
        state.phase !== "thinking" ||
        !isCurrent(state, event.turn, event.requestId)
      ) {
        return stale(state, "model-timeout", event.turn, event.requestId);
      }

      return [
        { ...state, phase: "recovery" },
        [{ type: "NOTICE", message: "The response took too long. Please try again." }],
      ];
    }

    case "PLAYBACK_STARTED": {
      if (
        state.phase === "preparingAudio" &&
        isCurrent(state, event.turn, event.requestId)
      ) {
        return [{ ...state, phase: "speaking" }, []];
      }

      // Playback may have crossed an interruption or cancellation boundary.
      // Stop it instead of accepting its late callback.
      return [
        state,
        [
          {
            type: "CANCEL_AUDIO",
            turn: event.turn,
            requestId: event.requestId,
          },
          {
            type: "LOG_STALE",
            source: "playback-start",
            turn: event.turn,
            requestId: event.requestId,
          },
        ],
      ];
    }

    case "PLAYBACK_ENDED": {
      if (
        state.phase !== "speaking" ||
        !isCurrent(state, event.turn, event.requestId)
      ) {
        return stale(state, "playback-end", event.turn, event.requestId);
      }

      return [{ phase: "idle", turn: state.turn }, []];
    }

    case "PLAYBACK_FAILED": {
      if (
        !["preparingAudio", "speaking"].includes(state.phase) ||
        !isCurrent(state, event.turn, event.requestId)
      ) {
        return stale(state, "playback-error", event.turn, event.requestId);
      }

      return [
        { ...state, phase: "recovery" },
        [{ type: "NOTICE", message: "Audio playback failed. A text answer can be shown." }],
      ];
    }

    case "DISCONNECTED": {
      const effects: Effect[] = [];

      if (
        (state.phase === "preparingAudio" || state.phase === "speaking") &&
        state.requestId
      ) {
        effects.push({
          type: "CANCEL_AUDIO",
          turn: state.turn,
          requestId: state.requestId,
        });
      }

      effects.push({ type: "NOTICE", message: "Connection lost. Reconnect to continue." });
      return [{ ...state, phase: "offline" }, effects];
    }
  }
}

There are two important design choices here.

First, turn changes as soon as new user speech begins. That immediately invalidates work from the previous turn.

Second, a playback callback is not automatically trusted. If audio starts after its turn was interrupted, the coordinator issues another cancellation rather than moving back into speaking.

Make the races executable

Create src/session.test.ts:

import { describe, expect, it } from "vitest";
import {
  type Effect,
  type Event,
  initialState,
  reduce,
} from "./session.js";

function scenario() {
  let state = initialState;

  return {
    step(event: Event): Effect[] {
      const [next, effects] = reduce(state, event);
      state = next;
      return effects;
    },
    state() {
      return state;
    },
  };
}

describe("voice turn protocol", () => {
  it("rejects an LLM result from an interrupted turn", () => {
    const s = scenario();

    s.step({ type: "USER_STARTED" });
    s.step({ type: "USER_ENDED" });
    s.step({
      type: "TRANSCRIPT_READY",
      turn: 1,
      requestId: "req-1",
      text: "Tell me a story",
    });

    // The user begins a replacement turn before req-1 completes.
    s.step({ type: "USER_STARTED" });
    s.step({ type: "USER_ENDED" });
    s.step({
      type: "TRANSCRIPT_READY",
      turn: 2,
      requestId: "req-2",
      text: "Actually, stop",
    });

    const effects = s.step({
      type: "MODEL_DONE",
      turn: 1,
      requestId: "req-1",
      text: "Once upon a time...",
    });

    expect(effects.some((effect) => effect.type === "SPEAK")).toBe(false);
    expect(s.state()).toMatchObject({
      phase: "thinking",
      turn: 2,
      requestId: "req-2",
    });
  });

  it("cancels playback that starts after a barge-in", () => {
    const s = scenario();

    s.step({ type: "USER_STARTED" });
    s.step({ type: "USER_ENDED" });
    s.step({
      type: "TRANSCRIPT_READY",
      turn: 1,
      requestId: "req-1",
      text: "Say hello",
    });
    s.step({
      type: "MODEL_DONE",
      turn: 1,
      requestId: "req-1",
      text: "Hello!",
    });

    const interruption = s.step({ type: "USER_STARTED" });
    expect(interruption).toContainEqual({
      type: "CANCEL_AUDIO",
      turn: 1,
      requestId: "req-1",
    });

    const lateStart = s.step({
      type: "PLAYBACK_STARTED",
      turn: 1,
      requestId: "req-1",
    });

    expect(lateStart).toContainEqual({
      type: "CANCEL_AUDIO",
      turn: 1,
      requestId: "req-1",
    });
    expect(s.state().phase).toBe("userSpeaking");
  });

  it("does not speak a response that arrives after timeout", () => {
    const s = scenario();

    s.step({ type: "USER_STARTED" });
    s.step({ type: "USER_ENDED" });
    s.step({
      type: "TRANSCRIPT_READY",
      turn: 1,
      requestId: "req-1",
      text: "What should we do today?",
    });
    s.step({
      type: "MODEL_TIMEOUT",
      turn: 1,
      requestId: "req-1",
    });

    const lateResult = s.step({
      type: "MODEL_DONE",
      turn: 1,
      requestId: "req-1",
      text: "Let us go for a walk.",
    });

    expect(lateResult.some((effect) => effect.type === "SPEAK")).toBe(false);
    expect(s.state().phase).toBe("recovery");
  });

  it.each([
    "The meeting starts at 3 PM.",
    "Your meeting begins at 3 PM.",
  ])("accepts a protocol-valid wording: %s", (answer) => {
    const s = scenario();

    s.step({ type: "USER_STARTED" });
    s.step({ type: "USER_ENDED" });
    s.step({
      type: "TRANSCRIPT_READY",
      turn: 1,
      requestId: "req-1",
      text: "When is my meeting?",
    });

    const effects = s.step({
      type: "MODEL_DONE",
      turn: 1,
      requestId: "req-1",
      text: answer,
    });

    expect(effects).toContainEqual({
      type: "SPEAK",
      turn: 1,
      requestId: "req-1",
      text: answer,
    });
  });
});

Run the suite:

npm test

These tests do not claim that both meeting answers are factually correct. They establish that wording variation is not a turn-protocol failure. Factual correctness needs its own evidence and oracle.

Use three test oracles, not one giant assertion

A practical test strategy separates concerns:

Layer	Suitable oracle	Example failure
Turn protocol	Deterministic state and effect assertions	Interrupted turn begins playback
Safety and policy	Rules, schemas, allowlists, and human-approved cases	Companion gives disallowed advice
Open-ended quality	Rubrics, reference facts, sampled human review	Answer is confusing despite being allowed

An LLM-based evaluator can assist the third layer, but it should not silently become the authority for the first two. If an evaluator says a response is acceptable while the response belongs to a stale turn, the application must still reject it.

Likewise, when a test and an LLM disagree, inspect the contract before changing either one:

Is the expected behavior explicitly documented?
Is the assertion about protocol, policy, or prose?
Would multiple outputs satisfy the user’s intent?
Could the test pass for the wrong reason?
Does accepting the output weaken a safety or control boundary?

This turns “the model was right” from a rhetorical conclusion into a reviewable engineering decision.

Connect the effects to the live voice path

Keep vendor and network operations behind ports:

export interface VoicePorts {
  requestTranscript(turn: number): Promise<void>;

  requestModel(input: {
    turn: number;
    requestId: string;
    text: string;
  }): Promise<void>;

  speak(input: {
    turn: number;
    requestId: string;
    text: string;
  }): Promise<void>;

  cancelAudio(input: {
    turn: number;
    requestId: string;
  }): Promise<void>;

  showNotice(message: string): void;
}

Your effect dispatcher translates application effects into the configured speech recognition, LLM, synthesis, and RTC operations. The corresponding callbacks are translated back into reducer events.

For the LLM path, preserve the same application request identifier through the configured integration where supported. The Tencent RTC LLM configuration documentation is the implementation reference for connecting an OpenAI-compatible model or an agent platform such as Dify or Coze.

Do not let the adapter mutate session state directly. Its job is to report outcomes such as MODEL_DONE, MODEL_TIMEOUT, or PLAYBACK_FAILED. The reducer decides whether those outcomes are still current.

Latency needs phase measurements

A single “response latency” number cannot tell you where a turn stalled. Record timestamps around boundaries such as:

type TurnTiming = {
  turn: number;
  requestId: string;
  userEndedAt?: number;
  transcriptReadyAt?: number;
  modelRequestedAt?: number;
  modelCompletedAt?: number;
  playbackRequestedAt?: number;
  playbackStartedAt?: number;
};

From those fields, derive separate measurements for:

End of user speech to transcript readiness
Model request to model completion
Speech preparation request to audible playback
Total end-of-speech to first playback

Choose timeout budgets from measurements in your own supported environments. Do not hide a slow phase behind automatic retries: a retry can produce a second, even later answer after the user has moved on.

The user-visible fallback should also match the failed phase. “I didn’t catch that” is appropriate for transcription failure but misleading when the model timed out.

Failure drills for a real companion

Unit tests prove reducer behavior. Staging drills prove that adapters preserve it.

Delayed ASR callback

Start one utterance, begin another, and release the first transcript afterward.

Expected: The old transcript is logged as stale and never reaches the LLM.

LLM completion after recovery is shown

Delay model completion beyond the application deadline.

Expected: Recovery remains visible. The late answer is not synthesized.

Playback starts after cancellation

Introduce a delay between requesting synthesis and receiving the playback-start callback. Interrupt during that gap.

Expected: The late audio is cancelled immediately. State remains with the user’s new turn.

Playback fails after valid model output

Make speech output unavailable while retaining the model result.

Expected: The interface exposes a clear fallback, such as displaying the text. It must not pretend the answer was spoken.

Connection loss during assistant speech

Disconnect the RTC path while audio is active.

Expected: Local playback is stopped, the session becomes visibly offline, and reconnection requires an explicit application policy.

Duplicate callback delivery

Deliver MODEL_DONE or PLAYBACK_ENDED twice.

Expected: The duplicate cannot trigger a second spoken answer or advance a later turn.

Preserve human control in the interface

A social or companion experience should make its AI nature clear and provide visible controls for muting, interrupting, ending the session, and managing any retained transcript data. Moderation and privacy decisions belong to the application design; fluent output is not evidence that those decisions are safe.

For character dialogue, AI companions, voice rooms, and related use cases, Tencent RTC also describes the broader Social Entertainment solution. Treat that page as scenario context, while using the product documentation for implementation details.

Release verification checklist

Before shipping, verify that:

[ ] Every turn receives an application-owned monotonic turn number.
[ ] Every model request has a correlation identifier.
[ ] A new user utterance invalidates previous asynchronous work.
[ ] Stale model output cannot reach synthesis.
[ ] Late playback is actively cancelled, not merely ignored in state.
[ ] Transcription, model, and playback failures have distinct recovery messages.
[ ] Timeouts leave the session in a defined state.
[ ] Duplicate callbacks are harmless.
[ ] Protocol tests do not require one exact natural-language sentence.
[ ] Policy tests remain deterministic where possible.
[ ] Open-ended quality judgments have a documented rubric and human review path.
[ ] Users can interrupt, mute, and leave without asking the AI for permission.

The useful reframing is simple: a failed test is evidence of disagreement, not automatic proof that either the implementation or the model is correct. In a live voice application, the strongest tests are the ones that defend turn ownership and human control while leaving room for valid language variation.

Relationship disclosure: This article was produced in connection with Tencent RTC. Official Tencent RTC documentation was used as the implementation reference.

Discussion

Which assertion in your current AI test suite is really a protocol guarantee—and which one is only an accidental preference for a particular wording?

Build a Community Digest That Shows What AI Did—and Did Not—Summarize

LunarDrift — Sat, 24 Oct 2026 17:10:40 +0000

Community opportunity channels create an uncomfortable trade-off: read every message or trust a summary that may omit the one deadline you needed.

An AI-generated digest can reduce reading time, but it cannot remove that uncertainty by itself. A model may shorten text reasonably well, yet still skip a qualification, alter a date, or give disproportionate attention to one post. The human concern underneath the AI discussion is not simply accuracy. It is loss of control over what gets noticed.

The safer design is to keep selection deterministic and use AI only for presentation:

People explicitly consent to having a post included.
The application freezes an ordered manifest of every eligible post.
AI may draft a summary for each item, but it cannot select or remove items.
A curator reviews AI-written text alongside the original.
The checkpoint advances only after publication is verified.

This tutorial builds that control layer in TypeScript, then shows where it connects to a Tencent RTC Social Messaging community.

Define the integrity rule

Our digest will follow one central invariant:

Every consented, eligible message inside the frozen sequence window must have a visible manifest entry, even if summarization fails.

That is stronger than asking an LLM to “summarize everything important.” Importance is subjective, while inclusion can be tested.

We will also separate four decisions that are often accidentally bundled together:

Decision	Authority
Whether a post enters the digest	Author consent plus deterministic channel policy
Whether content violates community rules	Existing moderation process
How a post is shortened	Optional AI draft
Whether the draft is published	Human curator

AI is useful here as a compression tool. It is not demonstrated to be a reliable authority for deadlines, eligibility, safety, or editorial priority.

Use an application-owned sequence

Timestamps are not sufficient for a reliable cursor. Two messages can share a timestamp, clocks can differ, and late ingestion can put an older timestamp after the checkpoint.

Assign each ingested community message a monotonically increasing application sequence:

101  Message A
102  Message B
103  Message C
        ^ frozen ceiling

A digest records both its starting checkpoint and its frozen ceiling. New messages receive higher sequence values and belong to the next run.

The minimum source record looks like this:

export interface SourceMessage {
  communityId: string;
  messageId: string;
  sequence: number;
  version: number;
  authorId: string;
  text: string | null;
  digestConsent: boolean;
  deleted: boolean;
}

digestConsent should come from a visible posting control such as “Include this resource in the scheduled digest.” Do not infer consent from public visibility.

version changes whenever the source content or consent state changes. That lets the reviewer detect edits made after collection.

Create the project

Use a current Node.js release with TypeScript support:

mkdir controlled-community-digest
cd controlled-community-digest
npm init -y
npm install --save-dev typescript tsx @types/node
npm pkg set type=module
npm pkg set scripts.test="tsx --test src/digest.test.ts"
mkdir src

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Represent omissions as states, not missing array entries

Create src/digest.ts:

export interface SourceMessage {
  communityId: string;
  messageId: string;
  sequence: number;
  version: number;
  authorId: string;
  text: string | null;
  digestConsent: boolean;
  deleted: boolean;
}

export type ItemState =
  | "ai_draft"
  | "verbatim_fallback"
  | "unsupported_content"
  | "changed_after_collection"
  | "withdrawn";

export interface DigestItem {
  messageId: string;
  sourceSequence: number;
  sourceVersion: number;
  originalText: string | null;
  summary?: string;
  state: ItemState;
  failureReason?: string;
}

export type DigestState =
  | "collecting"
  | "awaiting_review"
  | "approved"
  | "sending"
  | "delivery_unknown"
  | "checkpoint_pending"
  | "published";

export interface Digest {
  id: string;
  communityId: string;
  afterSequence: number;
  throughSequence: number;
  state: DigestState;
  items: DigestItem[];
  reviewerId?: string;
  receiptId?: string;
  lastError?: string;
}

export interface Summarizer {
  summarize(input: {
    messageId: string;
    text: string;
  }): Promise<string>;
}

Notice that an unsupported, withdrawn, or failed item still occupies a position in items. If the implementation simply filtered those entries out, a reviewer could not distinguish “intentionally excluded” from “silently lost.”

Freeze the manifest before calling AI

Add the collection function:

export async function buildDigest(input: {
  id: string;
  communityId: string;
  afterSequence: number;
  throughSequence: number;
  messages: SourceMessage[];
  summarizer?: Summarizer;
}): Promise<Digest> {
  const eligible = input.messages
    .filter((message) =>
      message.communityId === input.communityId &&
      message.sequence > input.afterSequence &&
      message.sequence <= input.throughSequence &&
      message.digestConsent
    )
    .sort((a, b) => a.sequence - b.sequence);

  const digest: Digest = {
    id: input.id,
    communityId: input.communityId,
    afterSequence: input.afterSequence,
    throughSequence: input.throughSequence,
    state: "collecting",
    items: eligible.map((message) => ({
      messageId: message.messageId,
      sourceSequence: message.sequence,
      sourceVersion: message.version,
      originalText: message.text,
      state: message.deleted ? "withdrawn" : "verbatim_fallback"
    }))
  };

  for (const item of digest.items) {
    if (item.state === "withdrawn") continue;

    if (item.originalText === null) {
      item.state = "unsupported_content";
      item.failureReason = "This digest only summarizes text content.";
      continue;
    }

    if (!input.summarizer) {
      item.state = "verbatim_fallback";
      continue;
    }

    try {
      const summary = await input.summarizer.summarize({
        messageId: item.messageId,
        text: item.originalText
      });

      if (summary.trim().length === 0) {
        throw new Error("The summarizer returned empty text.");
      }

      item.summary = summary.trim();
      item.state = "ai_draft";
    } catch (error) {
      item.state = "verbatim_fallback";
      item.failureReason =
        error instanceof Error ? error.message : "Unknown summarization failure";
    }
  }

  digest.state = "awaiting_review";
  return digest;
}

The manifest is built before the first model request. A model timeout therefore changes only an item's presentation state; it cannot make the source disappear.

In production, consider bounded concurrency rather than the serial loop shown here. Preserve the frozen manifest and item order regardless of how many model calls run concurrently.

Revalidate immediately before approval

A post may be edited, deleted, or withdrawn while the AI is working. Approval must compare the draft with current source versions.

Add this function:

export function revalidateDigest(
  digest: Digest,
  currentMessages: Map<string, SourceMessage>
): Digest {
  if (digest.state !== "awaiting_review") {
    throw new Error(`Cannot revalidate a digest in state ${digest.state}`);
  }

  for (const item of digest.items) {
    const current = currentMessages.get(item.messageId);

    if (!current || current.deleted || !current.digestConsent) {
      item.state = "withdrawn";
      item.summary = undefined;
      item.originalText = null;
      item.failureReason = "Source was deleted or digest consent was withdrawn.";
      continue;
    }

    if (current.version !== item.sourceVersion) {
      item.state = "changed_after_collection";
      item.summary = undefined;
      item.originalText = current.text;
      item.sourceVersion = current.version;
      item.failureReason = "Source changed; regenerate or review the current text.";
    }
  }

  return digest;
}

A changed item is not automatically sent back to AI. That choice should be visible to the curator: regenerate it, publish a verbatim excerpt, or defer it to the next digest.

Make human approval item-specific

A single “Approve digest” button can conceal unread AI output. Require the reviewer to acknowledge every AI-authored item:

export function approveDigest(input: {
  digest: Digest;
  reviewerId: string;
  reviewedAiMessageIds: Set<string>;
}): Digest {
  const { digest, reviewerId, reviewedAiMessageIds } = input;

  if (digest.state !== "awaiting_review") {
    throw new Error(`Cannot approve a digest in state ${digest.state}`);
  }

  const unresolved = digest.items.filter(
    (item) => item.state === "changed_after_collection"
  );

  if (unresolved.length > 0) {
    throw new Error("Resolve changed source messages before approval.");
  }

  const unreviewedAiItems = digest.items.filter(
    (item) =>
      item.state === "ai_draft" &&
      !reviewedAiMessageIds.has(item.messageId)
  );

  if (unreviewedAiItems.length > 0) {
    throw new Error("Every AI draft must be acknowledged by the reviewer.");
  }

  digest.reviewerId = reviewerId;
  digest.state = "approved";
  return digest;
}

The review interface should place the original and draft side by side. Highlight dates, URLs, monetary amounts, eligibility language, and proper names for human comparison. Those highlights can be deterministic; they do not need another model.

Treat a send timeout as uncertainty

A network timeout does not prove that publication failed. Blindly retrying can produce duplicate digests.

Model the publisher outcome explicitly:

export type PublishOutcome =
  | { kind: "accepted"; receiptId: string }
  | { kind: "rejected"; reason: string }
  | { kind: "unknown"; reason: string };

export interface DigestPublisher {
  publish(input: {
    communityId: string;
    digestId: string;
    body: string;
  }): Promise<PublishOutcome>;
}

export interface CheckpointStore {
  commit(input: {
    digestId: string;
    communityId: string;
    expectedAfter: number;
    through: number;
  }): Promise<void>;
}

export function renderDigest(digest: Digest): string {
  const lines = digest.items.map((item, index) => {
    const heading = `${index + 1}. Source message ${item.messageId}`;

    switch (item.state) {
      case "ai_draft":
        return `${heading}\nAI-assisted summary: ${item.summary}`;
      case "verbatim_fallback":
        return `${heading}\nOriginal excerpt: ${item.originalText}`;
      case "unsupported_content":
        return `${heading}\nNot summarized: unsupported content type.`;
      case "withdrawn":
        return `${heading}\nWithdrawn before publication.`;
      case "changed_after_collection":
        throw new Error("Changed items cannot be rendered for publication.");
    }
  });

  return [
    "Community resource digest",
    "AI-assisted text is labeled. Verify details against the source message.",
    "",
    ...lines
  ].join("\n");
}

export async function publishDigest(input: {
  digest: Digest;
  publisher: DigestPublisher;
  checkpoints: CheckpointStore;
}): Promise<Digest> {
  const { digest, publisher, checkpoints } = input;

  if (digest.state !== "approved" && digest.state !== "checkpoint_pending") {
    throw new Error(`Cannot publish a digest in state ${digest.state}`);
  }

  if (digest.state === "approved") {
    digest.state = "sending";

    const outcome = await publisher.publish({
      communityId: digest.communityId,
      digestId: digest.id,
      body: renderDigest(digest)
    });

    if (outcome.kind === "unknown") {
      digest.state = "delivery_unknown";
      digest.lastError = outcome.reason;
      return digest;
    }

    if (outcome.kind === "rejected") {
      digest.state = "approved";
      digest.lastError = outcome.reason;
      return digest;
    }

    digest.receiptId = outcome.receiptId;
    digest.state = "checkpoint_pending";
  }

  try {
    await checkpoints.commit({
      digestId: digest.id,
      communityId: digest.communityId,
      expectedAfter: digest.afterSequence,
      through: digest.throughSequence
    });

    digest.state = "published";
    digest.lastError = undefined;
  } catch (error) {
    digest.state = "checkpoint_pending";
    digest.lastError =
      error instanceof Error ? error.message : "Checkpoint commit failed";
  }

  return digest;
}

There are two important recovery paths:

delivery_unknown: inspect the community timeline or reconcile through an application-owned publication record before retrying.
checkpoint_pending: publication was accepted, so recovery retries only the conditional checkpoint commit—not the message publication.

The production checkpoint operation should be conditional on expectedAfter and idempotent by digestId. That prevents two scheduler instances from advancing the same community cursor independently.

Reproduce the dangerous cases

Create src/digest.test.ts:

import test from "node:test";
import assert from "node:assert/strict";
import {
  approveDigest,
  buildDigest,
  publishDigest,
  revalidateDigest,
  type SourceMessage
} from "./digest.js";

const source = (overrides: Partial<SourceMessage> = {}): SourceMessage => ({
  communityId: "community-1",
  messageId: "message-1",
  sequence: 11,
  version: 1,
  authorId: "author-1",
  text: "Applications close Friday. Check the source for eligibility.",
  digestConsent: true,
  deleted: false,
  ...overrides
});

test("a failed AI call preserves the source as a fallback", async () => {
  const digest = await buildDigest({
    id: "digest-1",
    communityId: "community-1",
    afterSequence: 10,
    throughSequence: 11,
    messages: [source()],
    summarizer: {
      summarize: async () => {
        throw new Error("model timeout");
      }
    }
  });

  assert.equal(digest.items.length, 1);
  assert.equal(digest.items[0]?.state, "verbatim_fallback");
  assert.equal(digest.items[0]?.failureReason, "model timeout");
});

test("an edit after collection blocks approval", async () => {
  const digest = await buildDigest({
    id: "digest-2",
    communityId: "community-1",
    afterSequence: 10,
    throughSequence: 11,
    messages: [source()],
    summarizer: {
      summarize: async () => "Applications close Friday."
    }
  });

  revalidateDigest(
    digest,
    new Map([
      ["message-1", source({ version: 2, text: "Deadline extended to Monday." })]
    ])
  );

  assert.equal(digest.items[0]?.state, "changed_after_collection");
  assert.throws(() =>
    approveDigest({
      digest,
      reviewerId: "curator-1",
      reviewedAiMessageIds: new Set()
    })
  );
});

test("unknown delivery does not advance the checkpoint", async () => {
  const digest = await buildDigest({
    id: "digest-3",
    communityId: "community-1",
    afterSequence: 10,
    throughSequence: 11,
    messages: [source()]
  });

  approveDigest({
    digest,
    reviewerId: "curator-1",
    reviewedAiMessageIds: new Set()
  });

  let checkpointCommits = 0;

  await publishDigest({
    digest,
    publisher: {
      publish: async () => ({
        kind: "unknown",
        reason: "request timed out after submission"
      })
    },
    checkpoints: {
      commit: async () => {
        checkpointCommits += 1;
      }
    }
  });

  assert.equal(digest.state, "delivery_unknown");
  assert.equal(checkpointCommits, 0);
});

Run the suite:

npm test

These tests verify the control boundary, not an LLM's prose quality. Summary quality needs an evaluation set containing the kinds of community posts you actually publish, especially posts with dates, restrictions, corrections, and multiple links.

Connect the workflow to Tencent RTC Social Messaging

Tencent RTC's Social Messaging solution covers group discussions and community experiences, which makes the community conversation the appropriate user-facing surface for this workflow:

https://trtc.io/solutions/social-messaging

Keep the integration behind adapters rather than inventing product methods:

interface CommunityMessagingAdapter {
  ingestIntoApplicationLedger(): Promise<void>;
  publishDigestMessage(input: {
    communityId: string;
    digestId: string;
    body: string;
  }): Promise<PublishOutcome>;
}

Implement those methods using the documented SDK and version selected by your application. The application-owned ledger remains responsible for sequences, source versions, consent, review state, and checkpoints.

A practical deployment flow is:

Tencent RTC community conversation
              │
              ▼
 Application ingestion ledger ── assigns sequence and version
              │
              ▼
 Frozen consented manifest
              │
       optional AI summaries
              │
              ▼
      Human review interface
              │
              ▼
 Community digest publication
              │
              ▼
 Conditional checkpoint commit

Do not send private, deleted, or consent-withdrawn content to a summarizer. Apply your privacy and moderation requirements before model invocation, and retain only the data required by your policy.

Translation remains reader-controlled

A multilingual community may also offer on-demand translation. Tencent RTC documents TUIChat message translation here:

https://trtc.io/document/60772

The documentation includes supported content types, languages, and edition limitations, so verify those conditions for your deployment rather than assuming every digest can be translated.

Translation should remain a display operation:

Preserve the published digest in its original language.
Label translated text.
Keep source message references visible.
Never feed translated text back into consent, moderation, checkpoint, or approval decisions.

If a translated deadline conflicts with the original, the original source remains authoritative and should be escalated to a person.

Decide the user-visible response to each failure

Failure	Internal state	What the user or curator sees
AI request times out	`verbatim_fallback`	Original excerpt plus a summarization-failed label
AI returns empty text	`verbatim_fallback`	Same fallback; item is not removed
Non-text post is included	`unsupported_content`	Visible source entry without an invented description
Author edits the post	`changed_after_collection`	Approval blocked until the new version is handled
Author withdraws consent	`withdrawn`	Content removed; withdrawal remains visible in the manifest
Publication is rejected	`approved`	Correct the known error and retry
Publication result is uncertain	`delivery_unknown`	Reconcile before retrying
Publication succeeds but cursor storage fails	`checkpoint_pending`	Retry only the checkpoint commit
Curator is unavailable	`awaiting_review`	Digest waits; AI cannot self-approve

This table is also a useful product requirement. If a state has no understandable interface treatment, it is probably not ready for production.

Pre-release verification

Run these checks with a staging community:

[ ] Two scheduler instances cannot claim the same checkpoint window.
[ ] Every consented message in the frozen window creates one manifest item.
[ ] AI failure cannot reduce the manifest item count.
[ ] A source edit invalidates its old summary.
[ ] Consent withdrawal removes source content before publication.
[ ] A curator must acknowledge every AI-authored item.
[ ] Dates, URLs, amounts, and eligibility wording are compared with the original.
[ ] Unsupported content is labeled rather than guessed.
[ ] An uncertain send does not advance the checkpoint.
[ ] A checkpoint failure does not republish an accepted digest.
[ ] Empty windows advance through an audited, conditional operation so they are not scanned forever.
[ ] Translation support is checked against the documented content, language, and edition constraints.
[ ] The interface clearly labels AI-assisted summaries and provides access to source messages.
[ ] Retention and model-data policies match the community's consent language.

The skill that remains valuable

The durable engineering skill here is not writing a more persuasive summarization prompt. It is deciding which parts of a community workflow may be probabilistic.

AI can draft shorter text. It should not quietly decide who gets visibility, whether consent still applies, or whether a delivery succeeded. Once those boundaries are represented as data and states, people can inspect the process instead of merely trusting its output.

For your own community, the useful design question is: Which omission would be most costly, and can your manifest prove that it did not happen?

Disclosure: This article was created in collaboration with Tencent RTC. Official Tencent RTC documentation was used as the implementation reference.

Your Community Showcase Needs a Work Queue, Not Another Chat Channel

LunarDrift — Sun, 18 Oct 2026 17:04:49 +0000

An enthusiastic community prompt can quietly become operational debt.

You invite people to nominate work for a showcase. The first few replies feel manageable. Then submissions keep arriving, reviewers assume somebody else owns them, and authors cannot tell whether the original promise still stands.

The uncomfortable part is not that the community participated too much. It is that a conversational promise became a queue without acquiring queue semantics.

Creating another channel rarely fixes this. It moves the same ambiguity somewhere fewer people can see it. A more reliable design keeps the existing community conversation as the surface while adding a small commitment ledger behind it.

In this tutorial, we will build that ledger in TypeScript. It will provide:

bounded admission, so the application cannot accept unlimited work;
one nomination per author, with idempotent retries;
explicit campaign states for accepting, draining, and closing;
reviewer leases, so every accepted item has temporary ownership;
protection against late reviewers completing reassigned work;
verifiable progress independent of chat-notification delivery.

Tencent RTC's Social Messaging solution covers the relevant conversation surfaces, including group discussions, communities, rich media, and interest-based social experiences. We will treat that messaging layer as the place where people discover and interact with the showcase—not as the database that decides whether a promise has been fulfilled.

First decide whether you need this machinery

Not every community prompt needs a workflow service.

Situation	Better choice
A casual request with no completion promise	Keep it as a normal thread
A small, time-boxed prompt owned by one moderator	Use a pinned checklist and publish a closing update
Every accepted submission must receive an action	Use a commitment ledger
Several reviewers can claim work	Use leases or another explicit assignment mechanism
The organizer needs to stop intake while finishing accepted work	Separate `open` from `draining`

The important distinction is conversation versus commitment. Messages can arrive in any order and may be missed. A commitment requires admission rules, ownership, terminal states, and a definition of done.

The lifecycle users should be able to see

Our campaign has three states:

open -----> draining -----> closed
  |             |
  |             +-- no new submissions
  +-- accepts work while capacity and deadline allow

Each accepted entry follows a separate lifecycle:

queued -----> leased -----> done
   |              |
   |              +-------> queued    (lease expires)
   |
   +----------------------> withdrawn

draining matters because “we stopped accepting submissions” is not the same as “we completed the promise.” Closing the campaign while entries remain queued would hide unfinished work.

A reviewer claim is a lease rather than permanent ownership. If a browser closes or a worker crashes, the entry becomes claimable after the lease expires. Each lease receives a token, preventing the original reviewer from submitting a late result after somebody else has taken over.

Create the reproducible project

Use Node.js 20 or later:

mkdir community-promise-ledger
cd community-promise-ledger
npm init -y
npm install --save-dev typescript tsx @types/node
mkdir src

Add the test command to package.json:

{
  "scripts": {
    "test": "tsx src/ledger.test.ts"
  }
}

Now create src/ledger.ts:

import { randomUUID } from "node:crypto";

export type CampaignState = "open" | "draining" | "closed";
export type EntryState = "queued" | "leased" | "done" | "withdrawn";

export type Campaign = {
  id: string;
  state: CampaignState;
  capacity: number;
  acceptedCount: number;
  closesAt: number;
};

export type Lease = {
  token: string;
  reviewerId: string;
  expiresAt: number;
};

export type Entry = {
  id: string;
  campaignId: string;
  authorId: string;
  sourceConversationId: string;
  sourceMessageId: string;
  title: string;
  url: string;
  state: EntryState;
  createdAt: number;
  lease?: Lease;
  reviewSummary?: string;
  completedBy?: string;
};

export class LedgerError extends Error {
  constructor(public readonly code: string) {
    super(code);
  }
}

export class CommitmentLedger {
  private campaigns = new Map<string, Campaign>();
  private entries = new Map<string, Entry>();

  constructor(private readonly now: () => number = Date.now) {}

  createCampaign(input: {
    id: string;
    capacity: number;
    closesAt: number;
  }): Campaign {
    if (input.capacity < 1) throw new LedgerError("INVALID_CAPACITY");
    if (this.campaigns.has(input.id)) {
      throw new LedgerError("CAMPAIGN_EXISTS");
    }

    const campaign: Campaign = {
      ...input,
      state: "open",
      acceptedCount: 0,
    };

    this.campaigns.set(campaign.id, campaign);
    return structuredClone(campaign);
  }

  submit(input: {
    campaignId: string;
    authorId: string;
    sourceConversationId: string;
    sourceMessageId: string;
    title: string;
    url: string;
  }): Entry {
    const campaign = this.requireCampaign(input.campaignId);

    const previous = [...this.entries.values()].find(
      entry =>
        entry.campaignId === input.campaignId &&
        entry.authorId === input.authorId,
    );

    // A repeated delivery of the same message returns the original receipt.
    if (previous?.sourceMessageId === input.sourceMessageId) {
      return structuredClone(previous);
    }

    if (previous) throw new LedgerError("AUTHOR_ALREADY_SUBMITTED");
    if (campaign.state !== "open") {
      throw new LedgerError("CAMPAIGN_NOT_OPEN");
    }
    if (this.now() >= campaign.closesAt) {
      throw new LedgerError("SUBMISSION_DEADLINE_PASSED");
    }
    if (campaign.acceptedCount >= campaign.capacity) {
      throw new LedgerError("CAMPAIGN_AT_CAPACITY");
    }

    const entry: Entry = {
      id: randomUUID(),
      campaignId: input.campaignId,
      authorId: input.authorId,
      sourceConversationId: input.sourceConversationId,
      sourceMessageId: input.sourceMessageId,
      title: input.title,
      url: input.url,
      state: "queued",
      createdAt: this.now(),
    };

    campaign.acceptedCount += 1;
    this.entries.set(entry.id, entry);
    return structuredClone(entry);
  }

  claimNext(
    campaignId: string,
    reviewerId: string,
    leaseDurationMs: number,
  ): Entry | undefined {
    if (leaseDurationMs < 1) throw new LedgerError("INVALID_LEASE");

    this.requireCampaign(campaignId);
    this.reapExpiredLeases(campaignId);

    const candidate = [...this.entries.values()]
      .filter(
        entry =>
          entry.campaignId === campaignId && entry.state === "queued",
      )
      .sort((a, b) => a.createdAt - b.createdAt)[0];

    if (!candidate) return undefined;

    candidate.state = "leased";
    candidate.lease = {
      token: randomUUID(),
      reviewerId,
      expiresAt: this.now() + leaseDurationMs,
    };

    return structuredClone(candidate);
  }

  complete(entryId: string, leaseToken: string, summary: string): Entry {
    const entry = this.requireEntry(entryId);

    if (entry.state !== "leased" || !entry.lease) {
      throw new LedgerError("ENTRY_NOT_LEASED");
    }
    if (entry.lease.token !== leaseToken) {
      throw new LedgerError("LEASE_TOKEN_MISMATCH");
    }
    if (this.now() >= entry.lease.expiresAt) {
      entry.state = "queued";
      delete entry.lease;
      throw new LedgerError("LEASE_EXPIRED");
    }
    if (!summary.trim()) throw new LedgerError("EMPTY_REVIEW");

    entry.state = "done";
    entry.reviewSummary = summary.trim();
    entry.completedBy = entry.lease.reviewerId;
    delete entry.lease;

    return structuredClone(entry);
  }

  withdraw(entryId: string, authorId: string): Entry {
    const entry = this.requireEntry(entryId);

    if (entry.authorId !== authorId) {
      throw new LedgerError("NOT_ENTRY_AUTHOR");
    }
    if (entry.state === "done") {
      throw new LedgerError("ENTRY_ALREADY_COMPLETED");
    }

    entry.state = "withdrawn";
    delete entry.lease;
    return structuredClone(entry);
  }

  beginDraining(campaignId: string): Campaign {
    const campaign = this.requireCampaign(campaignId);
    if (campaign.state !== "open") {
      throw new LedgerError("CAMPAIGN_NOT_OPEN");
    }

    campaign.state = "draining";
    return structuredClone(campaign);
  }

  close(campaignId: string): Campaign {
    const campaign = this.requireCampaign(campaignId);
    if (campaign.state !== "draining") {
      throw new LedgerError("CAMPAIGN_NOT_DRAINING");
    }

    this.reapExpiredLeases(campaignId);

    const unfinished = [...this.entries.values()].some(
      entry =>
        entry.campaignId === campaignId &&
        (entry.state === "queued" || entry.state === "leased"),
    );

    if (unfinished) throw new LedgerError("UNFINISHED_ENTRIES");

    campaign.state = "closed";
    return structuredClone(campaign);
  }

  progress(campaignId: string) {
    const relevant = [...this.entries.values()].filter(
      entry => entry.campaignId === campaignId,
    );

    return {
      accepted: relevant.length,
      queued: relevant.filter(entry => entry.state === "queued").length,
      leased: relevant.filter(entry => entry.state === "leased").length,
      done: relevant.filter(entry => entry.state === "done").length,
      withdrawn: relevant.filter(entry => entry.state === "withdrawn").length,
    };
  }

  private reapExpiredLeases(campaignId: string): void {
    for (const entry of this.entries.values()) {
      if (
        entry.campaignId === campaignId &&
        entry.state === "leased" &&
        entry.lease &&
        this.now() >= entry.lease.expiresAt
      ) {
        entry.state = "queued";
        delete entry.lease;
      }
    }
  }

  private requireCampaign(id: string): Campaign {
    const campaign = this.campaigns.get(id);
    if (!campaign) throw new LedgerError("CAMPAIGN_NOT_FOUND");
    return campaign;
  }

  private requireEntry(id: string): Entry {
    const entry = this.entries.get(id);
    if (!entry) throw new LedgerError("ENTRY_NOT_FOUND");
    return entry;
  }
}

This is intentionally an in-memory core. It makes the policy easy to reproduce before database behavior, SDK callbacks, or UI state can obscure it.

Make the ownership race fail in a test

Create src/ledger.test.ts:

import assert from "node:assert/strict";
import { CommitmentLedger, LedgerError } from "./ledger.js";

let clock = 1_000;
const ledger = new CommitmentLedger(() => clock);

ledger.createCampaign({
  id: "showcase-2026",
  capacity: 2,
  closesAt: 10_000,
});

const alice = ledger.submit({
  campaignId: "showcase-2026",
  authorId: "alice",
  sourceConversationId: "community-main",
  sourceMessageId: "message-101",
  title: "Alice's selected project",
  url: "https://example.test/alice",
});

// Redelivery of the same source message is idempotent.
const aliceRetry = ledger.submit({
  campaignId: "showcase-2026",
  authorId: "alice",
  sourceConversationId: "community-main",
  sourceMessageId: "message-101",
  title: "Alice's selected project",
  url: "https://example.test/alice",
});
assert.equal(aliceRetry.id, alice.id);

const bob = ledger.submit({
  campaignId: "showcase-2026",
  authorId: "bob",
  sourceConversationId: "community-main",
  sourceMessageId: "message-102",
  title: "Bob's selected project",
  url: "https://example.test/bob",
});

assert.throws(
  () =>
    ledger.submit({
      campaignId: "showcase-2026",
      authorId: "carol",
      sourceConversationId: "community-main",
      sourceMessageId: "message-103",
      title: "Carol's project",
      url: "https://example.test/carol",
    }),
  (error: unknown) =>
    error instanceof LedgerError && error.code === "CAMPAIGN_AT_CAPACITY",
);

const firstLease = ledger.claimNext("showcase-2026", "reviewer-a", 500)!;
assert.equal(firstLease.id, alice.id);

// Reviewer A disappears. The lease expires and Reviewer B receives the item.
clock += 501;
const secondLease = ledger.claimNext("showcase-2026", "reviewer-b", 500)!;
assert.equal(secondLease.id, alice.id);

// The late completion from Reviewer A must not overwrite Reviewer B's claim.
assert.throws(
  () => ledger.complete(alice.id, firstLease.lease!.token, "Late result"),
  (error: unknown) =>
    error instanceof LedgerError && error.code === "LEASE_TOKEN_MISMATCH",
);

ledger.complete(
  alice.id,
  secondLease.lease!.token,
  "Reviewed with an actionable response.",
);

const bobLease = ledger.claimNext("showcase-2026", "reviewer-c", 500)!;
ledger.withdraw(bob.id, "bob");

// Withdrawal invalidates an outstanding reviewer lease.
assert.throws(
  () => ledger.complete(bob.id, bobLease.lease!.token, "Should not commit"),
  (error: unknown) =>
    error instanceof LedgerError && error.code === "ENTRY_NOT_LEASED",
);

ledger.beginDraining("showcase-2026");
ledger.close("showcase-2026");

assert.deepEqual(ledger.progress("showcase-2026"), {
  accepted: 2,
  queued: 0,
  leased: 0,
  done: 1,
  withdrawn: 1,
});

console.log("All commitment-ledger checks passed.");

Run it:

npm test

You should see:

All commitment-ledger checks passed.

The critical assertion is not the happy-path completion. It is the rejection of Reviewer A's late result after the lease has been reassigned.

Connect it to a Tencent RTC community without inventing a second inbox

Use the Tencent RTC community or group discussion as the interaction surface. Keep the workflow integration behind an application-owned adapter instead of coupling policy to a particular UI callback:

export interface CommunitySurface {
  showCampaignCard(input: {
    conversationId: string;
    campaignId: string;
    state: "open" | "draining" | "closed";
    accepted: number;
    capacity: number;
  }): Promise<void>;

  acknowledgeSubmission(input: {
    conversationId: string;
    sourceMessageId: string;
    entryId: string;
    positionLabel: string;
  }): Promise<void>;

  announceClosure(input: {
    conversationId: string;
    completed: number;
    withdrawn: number;
  }): Promise<void>;
}

Map this adapter to the documented messaging integration used by your application. The ledger itself should not guess SDK method names or treat a rendered chat message as a successful database transition.

A practical request path is:

A member uses a “Nominate this work” action in the existing community conversation.
Your server authenticates the member and validates the submitted fields.
The ledger transaction accepts or rejects the nomination.
The response immediately renders the entry ID and current status to that member.
A community acknowledgement is posted as a separate delivery attempt.
The campaign card is refreshed from progress(), not from counted chat replies.

Step 4 prevents a notification failure from erasing the user's receipt. If step 5 fails, store the notification as pending and retry it separately. Do not run submit() again merely because acknowledgement delivery failed.

That gives you two independent facts:

Commitment fact: entry 8f... was accepted
Delivery fact: acknowledgement for entry 8f... is pending

Conflating those facts is how duplicate submissions and misleading “please retry” messages appear.

Production persistence needs four atomic guarantees

The in-memory implementation is deterministic but not safe across multiple server processes. Preserve these invariants when moving it to a database:

One author per campaign: enforce a unique constraint on (campaign_id, author_id).
Capacity admission: increment the accepted count and insert the entry in one transaction. If either fails, roll back both.
Exclusive claiming: claim only a queued entry—or atomically reclaim an expired lease—and store a new opaque token.
Conditional completion: update to done only when the entry is still leased with the supplied token and an unexpired lease.

Do not implement capacity as “count rows, then insert.” Two concurrent requests can both observe the final free slot. The capacity check must participate in the same transaction as admission.

Keep an append-only audit record for moderation and dispute handling:

type AuditEvent = {
  eventId: string;
  campaignId: string;
  entryId?: string;
  actorId: string;
  action:
    | "entry.accepted"
    | "entry.claimed"
    | "lease.expired"
    | "entry.completed"
    | "entry.withdrawn"
    | "campaign.draining"
    | "campaign.closed";
  occurredAt: number;
};

The audit log explains transitions; it does not replace the current-state table used for conditional writes.

Put translation around the workflow, not inside its authority rules

A multilingual community may need campaign instructions and reviewer responses translated. Tencent RTC documents on-demand text-message translation for TUIChat, together with applicable content types, supported languages, and edition limitations: TUIChat message translation.

Check those documented constraints for your deployment before presenting translation as available.

Translation should remain a display operation:

preserve the original campaign deadline and capacity values;
calculate state transitions from structured fields, not translated prose;
keep the original reviewer response accessible;
label translated text as translated;
let a translation failure leave the original message and ledger status usable.

For example, never parse “two places remaining” from either the original or translated message. Render that sentence from { capacity, acceptedCount } every time.

Failure behavior users can understand

A reliable workflow tells people what happened without asking them to infer it from silence.

Failure	Ledger behavior	User-visible response
Submission is delivered twice	Return the existing entry for the same source message	“Already accepted” with the original receipt
A different second nomination is submitted	Reject it	Link to the existing nomination and its status
Capacity is exhausted	Do not create an entry	“Intake is full; this work was not accepted”
Deadline passes	Do not create an entry	Show the recorded deadline and closed intake state
Reviewer closes the browser	Lease eventually expires	Return the entry to the review queue
Original reviewer returns late	Reject the stale token	Tell the reviewer the item was reassigned
Author withdraws during review	Invalidate the lease	Remove it from active reviewer work
Acknowledgement message fails	Keep the accepted entry	Show the receipt locally and retry notification
Translation fails	Preserve workflow state	Show the original text and a retry control
Moderator removes unsafe content	Apply the moderation policy and record the action	Show a neutral unavailable or removed state

External links and rich media should still pass your community's moderation and safety policy. Avoid fetching and publishing arbitrary previews before validation. Also decide whether review summaries are public, author-only, or moderator-only; that visibility choice should not be inferred from the entry state.

Release verification checklist

Before opening the real campaign, verify the whole procedure rather than only the reducer:

[ ] Two simultaneous requests cannot consume the same final capacity slot.
[ ] Redelivery of one source message returns the same entry ID.
[ ] A second, different submission from the same author is rejected clearly.
[ ] Intake stops at both the configured deadline and manual draining state.
[ ] An expired lease can be reassigned.
[ ] A stale lease token cannot complete reassigned work.
[ ] Author withdrawal invalidates an active lease.
[ ] The campaign cannot close with queued or leased entries.
[ ] A failed chat acknowledgement does not change admission state.
[ ] Progress is derived from ledger records, not message counts.
[ ] Original text remains available when translation fails.
[ ] Moderators can trace who accepted, claimed, completed, or withdrew an entry.
[ ] The final community update distinguishes completed, withdrawn, and unaccepted work.

The useful reframing

When participation exceeds expectations, the answer is not automatically more automation or another channel. First name what changed: a community conversation accumulated obligations.

Once that happens, reliability comes from making four things explicit:

what the community is still accepting;
which submissions were actually accepted;
who currently owns each accepted action;
what must be true before the promise can be called complete.

The chat remains where the community gathers. The ledger makes sure enthusiasm does not turn into invisible, unowned work.

Discussion: If your community makes a review, showcase, or mentorship promise, what counts as completion—and can contributors see that state without asking a moderator?

Disclosure: I wrote this article in collaboration with Tencent RTC, and used official Tencent RTC documentation as the implementation reference.

A Community Reply Is Not Permission to DM: Build a Consent Gate for 1:1 Chat

LunarDrift — Sat, 17 Oct 2026 17:10:35 +0000

A developer shares an opportunity in a community channel. Someone replies, “Can I ask you about this?” The natural product shortcut is to open a direct-message thread immediately.

That shortcut creates an uncomfortable ambiguity: being available in a community is not the same as agreeing to a private conversation.

The technical problem is not merely adding an “Accept” button. Acceptance can race with blocking, thread creation can fail, and a late callback can reopen a request that the recipient already declined. If an AI assistant drafts introductions, it adds another boundary: useful text generation must not become automated consent.

This tutorial builds a consent gate for moving from a Tencent RTC community interaction to 1:1 chat. The core is SDK-independent TypeScript, so its transition rules can be tested without a live messaging account.

Tencent RTC's Social Messaging solution covers community experiences alongside 1:1 and group chat. We will connect those capabilities through an application-owned consent workflow rather than assuming that membership in one context authorizes contact in another.

Define the user-visible contract

Our workflow has six promises:

A requester can ask to start a DM, but cannot accept for the recipient.
No composer is presented as ready until the recipient accepts and provisioning succeeds.
A block or decline wins over a late provisioning result.
Failed provisioning is visible and retryable; it is not silently reported as success.
AI may draft a request, but a person must review and submit it.
The original public context remains identifiable so the recipient knows why they were contacted.

This is an introduction-consent gate, not a complete abuse-prevention system. Once a DM is established, reporting, blocking, retention, and moderator escalation still need their own policies.

Model consent and provisioning separately

“Accepted” and “ready to message” are different facts. The recipient can grant consent while the application is still creating or locating the 1:1 conversation.

PENDING ──accept──> PROVISIONING ──success──> READY
   │                     │
   ├──decline──> DECLINED├──failure──> FAILED ──retry──> PROVISIONING
   ├──expire───> EXPIRED │
   └──block────> REVOKED <──block──────────────┘

A late success event is valid only while the request remains PROVISIONING. If the recipient blocks the requester first, the result must be ignored.

Create a small project:

mkdir consent-dm-gate
cd consent-dm-gate
npm init -y
npm install --save-dev typescript tsx vitest @types/node
npx tsc --init
mkdir src

Add the test command to package.json:

{
  "scripts": {
    "test": "vitest run"
  }
}

Implement the policy as a pure transition function

Create src/consent.ts:

export type Status =
  | "PENDING"
  | "PROVISIONING"
  | "READY"
  | "DECLINED"
  | "REVOKED"
  | "EXPIRED"
  | "FAILED";

export interface DmRequest {
  id: string;
  requesterId: string;
  recipientId: string;
  contextMessageId: string;
  status: Status;
  expiresAt: number;
  version: number;
  conversationRef?: string;
  failureCode?: "TEMPORARY" | "UNKNOWN_OUTCOME";
}

type Command =
  | { type: "ACCEPT"; actorId: string; now: number; blocked: boolean }
  | { type: "DECLINE"; actorId: string; now: number }
  | { type: "BLOCK"; actorId: string; now: number }
  | { type: "EXPIRE"; now: number }
  | { type: "PROVISION_OK"; conversationRef: string; now: number }
  | {
      type: "PROVISION_FAILED";
      code: "TEMPORARY" | "UNKNOWN_OUTCOME";
      now: number;
    }
  | { type: "RETRY"; actorId: string; now: number; blocked: boolean };

export class TransitionError extends Error {}

function changed(request: DmRequest, patch: Partial<DmRequest>): DmRequest {
  return { ...request, ...patch, version: request.version + 1 };
}

function requireRecipient(request: DmRequest, actorId: string): void {
  if (actorId !== request.recipientId) {
    throw new TransitionError("Only the recipient may perform this action");
  }
}

function requireNotExpired(request: DmRequest, now: number): void {
  if (now >= request.expiresAt) {
    throw new TransitionError("The request has expired");
  }
}

export function transition(request: DmRequest, command: Command): DmRequest {
  switch (command.type) {
    case "ACCEPT": {
      requireRecipient(request, command.actorId);
      requireNotExpired(request, command.now);

      if (request.status !== "PENDING") {
        throw new TransitionError(`Cannot accept from ${request.status}`);
      }
      if (command.blocked) {
        return changed(request, { status: "REVOKED" });
      }

      return changed(request, {
        status: "PROVISIONING",
        failureCode: undefined
      });
    }

    case "DECLINE": {
      requireRecipient(request, command.actorId);
      if (request.status !== "PENDING") {
        throw new TransitionError(`Cannot decline from ${request.status}`);
      }
      return changed(request, { status: "DECLINED" });
    }

    case "BLOCK": {
      requireRecipient(request, command.actorId);
      if (["DECLINED", "EXPIRED", "REVOKED"].includes(request.status)) {
        return request;
      }
      return changed(request, {
        status: "REVOKED",
        conversationRef: undefined
      });
    }

    case "EXPIRE": {
      if (request.status !== "PENDING" || command.now < request.expiresAt) {
        return request;
      }
      return changed(request, { status: "EXPIRED" });
    }

    case "PROVISION_OK": {
      // A callback arriving after decline, block, or another transition is stale.
      if (request.status !== "PROVISIONING") return request;

      return changed(request, {
        status: "READY",
        conversationRef: command.conversationRef,
        failureCode: undefined
      });
    }

    case "PROVISION_FAILED": {
      if (request.status !== "PROVISIONING") return request;
      return changed(request, {
        status: "FAILED",
        failureCode: command.code
      });
    }

    case "RETRY": {
      requireRecipient(request, command.actorId);
      requireNotExpired(request, command.now);

      if (request.status !== "FAILED") {
        throw new TransitionError(`Cannot retry from ${request.status}`);
      }
      if (command.blocked) {
        return changed(request, { status: "REVOKED" });
      }

      return changed(request, {
        status: "PROVISIONING",
        failureCode: undefined
      });
    }
  }
}

The blocked value must come from an authoritative application lookup performed during the transaction. Do not trust a browser-supplied boolean.

Reproduce the dangerous races

Create src/consent.test.ts:

import { describe, expect, it } from "vitest";
import { DmRequest, transition } from "./consent";

const base = (): DmRequest => ({
  id: "req-17",
  requesterId: "alex",
  recipientId: "sam",
  contextMessageId: "community-message-42",
  status: "PENDING",
  expiresAt: 2_000,
  version: 1
});

describe("DM consent gate", () => {
  it("does not let the requester accept", () => {
    expect(() =>
      transition(base(), {
        type: "ACCEPT",
        actorId: "alex",
        now: 1_000,
        blocked: false
      })
    ).toThrow("Only the recipient");
  });

  it("does not turn consent into readiness before provisioning", () => {
    const accepted = transition(base(), {
      type: "ACCEPT",
      actorId: "sam",
      now: 1_000,
      blocked: false
    });

    expect(accepted.status).toBe("PROVISIONING");
    expect(accepted.conversationRef).toBeUndefined();
  });

  it("lets a block defeat a late success result", () => {
    const provisioning = transition(base(), {
      type: "ACCEPT",
      actorId: "sam",
      now: 1_000,
      blocked: false
    });
    const revoked = transition(provisioning, {
      type: "BLOCK",
      actorId: "sam",
      now: 1_010
    });
    const late = transition(revoked, {
      type: "PROVISION_OK",
      conversationRef: "conversation-9",
      now: 1_020
    });

    expect(late.status).toBe("REVOKED");
    expect(late.conversationRef).toBeUndefined();
  });

  it("exposes a retryable provisioning failure", () => {
    const provisioning = transition(base(), {
      type: "ACCEPT",
      actorId: "sam",
      now: 1_000,
      blocked: false
    });
    const failed = transition(provisioning, {
      type: "PROVISION_FAILED",
      code: "TEMPORARY",
      now: 1_010
    });

    expect(failed.status).toBe("FAILED");
    expect(failed.failureCode).toBe("TEMPORARY");
  });

  it("does not accept an expired request", () => {
    expect(() =>
      transition(base(), {
        type: "ACCEPT",
        actorId: "sam",
        now: 2_000,
        blocked: false
      })
    ).toThrow("expired");
  });
});

Run the suite:

npm test

The important test is not the happy path. It is the late provisioning result after a block. Without that guard, an asynchronous callback can reverse a human decision.

Persist transitions with optimistic concurrency

The pure function protects one in-memory aggregate. Production storage must also prevent two servers from updating the same request from the same version.

A minimal relational record could look like this:

CREATE TABLE dm_requests (
  id                 TEXT PRIMARY KEY,
  requester_id       TEXT NOT NULL,
  recipient_id       TEXT NOT NULL,
  context_message_id TEXT NOT NULL,
  status             TEXT NOT NULL,
  expires_at         TIMESTAMPTZ NOT NULL,
  version            INTEGER NOT NULL,
  conversation_ref   TEXT,
  failure_code       TEXT,
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
  CHECK (requester_id <> recipient_id)
);

CREATE INDEX dm_requests_recipient_status
  ON dm_requests (recipient_id, status);

Write an accepted transition using a compare-and-swap update:

UPDATE dm_requests
SET status = 'PROVISIONING',
    version = version + 1,
    updated_at = now()
WHERE id = $1
  AND recipient_id = $2
  AND status = 'PENDING'
  AND version = $3
  AND expires_at > now()
RETURNING *;

If no row is returned, reload the request. It may have expired, been declined, been blocked in another transaction, or already been accepted.

Blocking and accepting must consult the same authoritative block relationship inside their transactions. Otherwise, this sequence remains possible:

Server A checks that no block exists.
Server B records a block.
Server A commits acceptance based on stale information.

Use row locking, serializable transactions, or a versioned relationship record appropriate to your database. The exact mechanism matters less than making the race an explicit design decision.

Connect the gate to Tencent RTC Social Messaging

Keep product integration behind a narrow port:

export interface DirectMessageConnector {
  ensureConversation(input: {
    requestId: string;
    requesterId: string;
    recipientId: string;
  }): Promise<{ conversationRef: string }>;
}

After the recipient accepts:

Commit PROVISIONING first.
Ask the connector to create or locate the relevant 1:1 conversation.
Commit READY only if the stored request is still PROVISIONING at the expected version.
If the operation definitely failed, record FAILED/TEMPORARY.
If the call timed out after being sent, record FAILED/UNKNOWN_OUTCOME and reconcile before creating anything again.

The adapter's SDK calls depend on the Tencent RTC Chat SDK, platform, and version you selected, so this tutorial deliberately does not invent method names. Use the current official integration documentation for that connector. The state machine remains the application contract around it.

An UNKNOWN_OUTCOME deserves special treatment. A timeout does not prove that the remote operation failed. A blind retry can create duplicate local mappings or confusing UI. First query or reconcile the conversation state using the supported facilities of your chosen integration, then finalize the original request.

Also distinguish a UI gate from an authorization boundary. Hiding a composer prevents accidental initiation, but it does not by itself stop a modified client. If your architecture requires strict enforcement, ensure that the path capable of initiating contact cannot bypass the server-side consent decision.

Render state instead of optimistic fiction

The recipient and requester should see different controls:

State	Recipient UI	Requester UI
`PENDING`	Accept, decline, block	Request sent; cancel if your policy supports it
`PROVISIONING`	“Opening conversation…”	“Waiting for conversation…”
`READY`	Open DM	Open DM
`FAILED`	Retry or cancel	“Could not open the conversation”
`DECLINED`	Dismissed	Declined, or a privacy-preserving generic result
`EXPIRED`	Request expired	Request expired
`REVOKED`	Block controls	No contact control

Whether the requester should be told “blocked” is a safety and privacy decision, not a database-display decision. A generic “This conversation cannot be opened” result often reveals less about the recipient's moderation choices.

Translation belongs after the consent decision

A multilingual community may need the recipient to understand why someone is asking to connect. Tencent RTC documents on-demand text-message translation through TUIChat in its message translation guide, including supported content, languages, and edition constraints that should be checked for the chosen deployment.

Treat translation as a reading aid around the request:

Retain and display the original introduction.
Label translated text as translated.
Do not convert translated text into an automatic accept, decline, or moderation command.
If translation is unavailable, leave the original visible and offer a retry rather than replacing it with guessed text.

Consent still comes from the recipient's explicit action, not from a translation result.

Where an AI assistant helps—and where it does not

An assistant can make a blank introduction box less awkward. For example, it can draft:

“I’m contacting you about the backend internship link you shared in the community thread. May I ask how you evaluated the role?”

That capability is useful but narrow. The model has not demonstrated that the recipient welcomes a DM, that the opportunity is still open, or that the drafted interpretation is correct.

A controlled implementation should therefore:

Pass only the public context the requester deliberately selects.
Generate a draft, not a sent message.
Show the source community message beside the draft.
Require the requester to edit or confirm it.
Run normal moderation checks on the submitted text.
Route ambiguous or serious safety reports to people rather than asking the model for a final judgment.

Do not silently add private profile data, previous DMs, or unrelated community history to the prompt. More context is not automatically better context; it can be an unexpected change in audience.

The human decision underneath the AI discussion is straightforward: who gets to decide that a public interaction becomes a private relationship? Text generation cannot make that decision for either participant.

Failure drills before release

Run these scenarios in staging, not only in unit tests:

Accept and block from two browser tabs at nearly the same time.
Expire a request while its acceptance screen is still open.
Disconnect the network after acceptance but before provisioning returns.
Return success after the request has been revoked.
Deliver the same success callback twice.
Make the connector time out with an unknown remote outcome.
Remove or hide the original community message after the request was created.
Submit an introduction that moderation holds for human review.
Make translation unavailable while preserving the original text.
Attempt to initiate contact from a modified client without a READY request.

For every drill, verify both persisted state and visible UI. A correct database row with a misleading “Message now” button is still a product failure.

Release checklist

[ ] Only the intended recipient can accept or decline.
[ ] Expiration is checked on the server.
[ ] Acceptance and blocking have a defined concurrency strategy.
[ ] PROVISIONING is visible and distinct from READY.
[ ] Late callbacks cannot reverse decline, expiry, or revocation.
[ ] Unknown outcomes are reconciled rather than blindly retried.
[ ] The original community context is identifiable.
[ ] Translations are labeled and do not replace the original.
[ ] AI output remains an editable draft.
[ ] Moderation includes a visible path to human review.
[ ] Modified clients cannot bypass the intended initiation policy.
[ ] Logs record request IDs and state transitions without unnecessarily copying message bodies.

A design question for your community

There is no universal expiry period or disclosure policy. A mentorship community, an event channel, and a peer-support space may need different defaults.

Before choosing the UI, decide these three things with moderators and members:

Does consent authorize one opening message or an ongoing conversation?
What context must a requester provide before the recipient decides?
Which outcomes should remain private from the requester?

Those answers determine the state machine more reliably than starting with a generic DM screen.

Disclosure: I have a content relationship with Tencent RTC, and I used official Tencent RTC documentation as the implementation reference for this article.

Translation Is Not Agreement: Build a Clarification Handshake for Multilingual Chat

LunarDrift — Fri, 16 Oct 2026 17:07:23 +0000

A multilingual chat can translate every word correctly and still leave someone wondering: Was that a suggestion, a deadline, or a polite refusal?

That uncertainty is not evidence that you are bad at communication—or that translation has failed. Natural languages encode tone, obligation, and context differently. The engineering mistake is treating translated text as if it removed those trade-offs.

This tutorial builds a clarification handshake for a Tencent RTC Social Messaging group:

A reader requests clarification about a specific message revision.
The request records what is unclear without rewriting the original message.
Only the original author can provide the authoritative answer.
Editing the source message supersedes outstanding requests.
Chat-notification failure remains visible instead of destroying the saved request.

Tencent RTC's Social Messaging scenario covers group discussions, communities, rich media, and other social experiences: https://trtc.io/solutions/social-messaging

TUIChat also provides on-demand text-message translation. Its documentation defines supported content types and languages as well as applicable edition limits: https://trtc.io/document/60772

Translation helps the reader understand the text. The handshake below answers a different question: Who gets to confirm what the message meant?

Start with three different kinds of uncertainty

Before adding a button, classify the user's problem:

User uncertainty	Appropriate action
“I cannot read this language”	Offer documented on-demand translation when supported
“I can read the words, but the intent is ambiguous”	Ask the original author for clarification
“This may violate a community rule”	Use the moderation or reporting workflow

Combining these paths creates dangerous shortcuts. A translated sentence should not automatically create a task, settle a dispute, or become a moderator's evidence of intent.

Our example UI will therefore place Translate and Ask what this means beside each other. Neither replaces the original message.

Define the protocol before the interface

A clarification request is attached to an exact source revision:

open
  ├── original author answers ──> resolved
  ├── source message changes ──> superseded
  └── requester cancels ───────> cancelled

Delivery of the chat notification is a separate state:

pending -> sent
pending -> failed       // definitely rejected; safe to retry
pending -> uncertain    // timeout or disconnect; do not retry blindly

That separation matters. If the request is saved but sending its notification times out, deleting the request would lose user work. Blindly retrying could instead produce duplicate messages.

The invariants are:

A translation is never stored as the author's statement.
Only the source-message author can resolve the request.
A request cannot silently move to a newer message revision.
Notification failure does not roll back the clarification record.
An uncertain send requires reconciliation or a deliberate user retry.

Create the reproducible project

Use Node.js 20 or later:

mkdir multilingual-clarification
cd multilingual-clarification
npm init -y
npm install --save-dev typescript tsx @types/node
mkdir src test

Add this test command to package.json:

{
  "scripts": {
    "test": "tsx --test test/*.test.ts"
  }
}

Implement the state model

Create src/clarifications.ts:

export type ClarificationStatus =
  | "open"
  | "resolved"
  | "superseded"
  | "cancelled";

export type NoticeState =
  | "pending"
  | "sent"
  | "failed"
  | "uncertain";

export type QuestionKind =
  | "literal_meaning"
  | "tone"
  | "required_action"
  | "other";

export interface Clarification {
  id: string;
  threadId: string;
  messageId: string;
  messageRevision: number;
  requesterId: string;
  authorId: string;
  kind: QuestionKind;
  note: string;
  status: ClarificationStatus;
  notice: NoticeState;
  createdAt: number;
  answer?: string;
  resolvedAt?: number;
  closedReason?: string;
}

export interface ChatPort {
  sendText(threadId: string, text: string): Promise<void>;
}

export class ChatSendError extends Error {
  constructor(public readonly certainty: "rejected" | "unknown") {
    super(`Chat send ${certainty}`);
  }
}

export class ClarificationService {
  private readonly rows = new Map<string, Clarification>();
  private sequence = 0;

  constructor(
    private readonly chat: ChatPort,
    private readonly now: () => number = Date.now,
  ) {}

  async create(input: {
    threadId: string;
    messageId: string;
    messageRevision: number;
    requesterId: string;
    authorId: string;
    kind: QuestionKind;
    note: string;
  }): Promise<Clarification> {
    if (input.requesterId === input.authorId) {
      throw new Error("Authors do not need a clarification request to themselves");
    }

    const note = input.note.trim();
    if (note.length > 280) {
      throw new Error("Clarification note is too long");
    }

    const id = `clarification-${++this.sequence}`;
    const row: Clarification = {
      ...input,
      id,
      note,
      status: "open",
      notice: "pending",
      createdAt: this.now(),
    };

    // Persist first. Sending a chat message is an external side effect.
    this.rows.set(id, row);
    await this.deliverNotice(id);

    return this.get(id);
  }

  async deliverNotice(id: string): Promise<void> {
    const row = this.mutable(id);

    if (row.notice === "sent") return;
    if (row.notice === "uncertain") {
      throw new Error("Reconcile an uncertain send before retrying");
    }

    row.notice = "pending";

    try {
      await this.chat.sendText(
        row.threadId,
        `Clarification ${row.id} requested for message ${row.messageId}.`,
      );
      row.notice = "sent";
    } catch (error) {
      row.notice =
        error instanceof ChatSendError && error.certainty === "rejected"
          ? "failed"
          : "uncertain";
    }
  }

  resolve(input: {
    id: string;
    actorId: string;
    currentMessageRevision: number;
    answer: string;
  }): Clarification {
    const row = this.mutable(input.id);

    if (row.status !== "open") {
      throw new Error(`Cannot resolve a ${row.status} request`);
    }

    if (input.actorId !== row.authorId) {
      throw new Error("Only the original author may resolve this request");
    }

    if (input.currentMessageRevision !== row.messageRevision) {
      row.status = "superseded";
      row.closedReason = "source_message_changed";
      throw new Error("The source message changed; create a new request");
    }

    const answer = input.answer.trim();
    if (!answer) throw new Error("An answer is required");

    row.status = "resolved";
    row.answer = answer;
    row.resolvedAt = this.now();
    return this.get(row.id);
  }

  sourceRevised(messageId: string, newRevision: number): void {
    for (const row of this.rows.values()) {
      if (
        row.messageId === messageId &&
        row.status === "open" &&
        row.messageRevision !== newRevision
      ) {
        row.status = "superseded";
        row.closedReason = "source_message_changed";
      }
    }
  }

  cancel(id: string, requesterId: string): Clarification {
    const row = this.mutable(id);

    if (row.requesterId !== requesterId) {
      throw new Error("Only the requester may cancel this request");
    }
    if (row.status !== "open") {
      throw new Error(`Cannot cancel a ${row.status} request`);
    }

    row.status = "cancelled";
    row.closedReason = "requester_cancelled";
    return this.get(id);
  }

  get(id: string): Clarification {
    return { ...this.mutable(id) };
  }

  private mutable(id: string): Clarification {
    const row = this.rows.get(id);
    if (!row) throw new Error(`Unknown clarification: ${id}`);
    return row;
  }
}

The ChatPort is intentionally small. It does not invent a Tencent RTC SDK method name. The application adapter should call the documented text-send operation from the Tencent RTC integration you actually use.

Verify authority, revisions, and delivery uncertainty

Create test/clarifications.test.ts:

import assert from "node:assert/strict";
import test from "node:test";
import {
  ChatPort,
  ChatSendError,
  ClarificationService,
} from "../src/clarifications.js";

const baseRequest = {
  threadId: "group-7",
  messageId: "message-42",
  messageRevision: 1,
  requesterId: "reader",
  authorId: "author",
  kind: "required_action" as const,
  note: "Is this optional, or should it be done today?",
};

test("only the original author can resolve a request", async () => {
  const chat: ChatPort = { sendText: async () => {} };
  const service = new ClarificationService(chat, () => 1000);
  const request = await service.create(baseRequest);

  assert.throws(
    () =>
      service.resolve({
        id: request.id,
        actorId: "another-member",
        currentMessageRevision: 1,
        answer: "It is required",
      }),
    /Only the original author/,
  );

  const resolved = service.resolve({
    id: request.id,
    actorId: "author",
    currentMessageRevision: 1,
    answer: "It is optional; tomorrow is also fine.",
  });

  assert.equal(resolved.status, "resolved");
  assert.equal(resolved.answer, "It is optional; tomorrow is also fine.");
});

test("editing the source supersedes an open request", async () => {
  const chat: ChatPort = { sendText: async () => {} };
  const service = new ClarificationService(chat);
  const request = await service.create(baseRequest);

  service.sourceRevised("message-42", 2);

  const current = service.get(request.id);
  assert.equal(current.status, "superseded");
  assert.equal(current.closedReason, "source_message_changed");
});

test("an ambiguous send failure is not retried automatically", async () => {
  let attempts = 0;
  const chat: ChatPort = {
    sendText: async () => {
      attempts += 1;
      throw new ChatSendError("unknown");
    },
  };

  const service = new ClarificationService(chat);
  const request = await service.create(baseRequest);

  assert.equal(request.status, "open");
  assert.equal(request.notice, "uncertain");
  assert.equal(attempts, 1);

  await assert.rejects(
    service.deliverNotice(request.id),
    /Reconcile an uncertain send/,
  );
  assert.equal(attempts, 1);
});

test("a definitely rejected notification can be retried", async () => {
  let attempts = 0;
  const chat: ChatPort = {
    sendText: async () => {
      attempts += 1;
      if (attempts === 1) throw new ChatSendError("rejected");
    },
  };

  const service = new ClarificationService(chat);
  const request = await service.create(baseRequest);

  assert.equal(request.notice, "failed");
  await service.deliverNotice(request.id);
  assert.equal(service.get(request.id).notice, "sent");
  assert.equal(attempts, 2);
});

Run the suite:

npm test

These tests verify the decisions that matter more than the button styling:

A fluent bystander cannot speak for the author.
An old clarification cannot be applied to edited text.
A timeout does not trigger an uncontrolled duplicate send.
A definite rejection remains recoverable.

Connect the workflow to TUIChat

Keep translation and clarification as neighboring capabilities rather than one pipeline.

Translation path

For a supported text message, let the user explicitly invoke TUIChat's documented on-demand translation experience. Before enabling it in a deployment, check the official documentation for:

supported message content types;
supported source and target languages;
applicable edition requirements;
the platform-specific integration instructions.

Do not copy a language list into application code and assume it will remain accurate. Treat the documentation and your verified deployment configuration as the capability source.

If translation is unavailable, preserve the original message and show an honest state such as:

Translation is not available for this message.
You can still ask the author for clarification.

Clarification path

The Ask what this means action should receive source data from the rendered message:

await clarifications.create({
  threadId: currentThread.id,
  messageId: selectedMessage.id,
  messageRevision: selectedMessage.revision,
  requesterId: currentUser.id,
  authorId: selectedMessage.authorId,
  kind: "tone",
  note: "Does this mean you agree, or that you want more discussion?",
});

The field names above belong to this tutorial's application model. Map them to identifiers and revision tracking that your own backend controls; they are not presented as Tencent RTC API names.

Render the resulting record as a card associated with the source message:

Clarification requested · Tone
“Does this mean you agree, or that you want more discussion?”
Waiting for the original author

When resolved:

Answered by the original author
“I agree with the direction, but not the proposed deadline.”

Do not parse the translated notification text to reconstruct state. The clarification record is the state; the chat message is only a user-visible notification.

Production persistence needs conditional writes

The in-memory map makes the state machine easy to reproduce, but a production backend should perform conditional database updates.

For example, resolving a request should be equivalent to:

UPDATE clarifications
SET status = 'resolved', answer = ?, resolved_at = ?
WHERE id = ?
  AND status = 'open'
  AND author_id = ?
  AND message_revision = ?;

Treat an affected-row count of zero as a conflict, not as success. Another process may have superseded, cancelled, or resolved the request first.

For chat notices, use an outbox worker if requests must survive a server restart. Still retain an uncertain state: a process can lose its connection after the messaging service accepts a send but before the worker records success. Unless your documented integration provides an appropriate deduplication mechanism, do not promise exactly-once notification delivery.

A duplicate notice with the same clarification ID is preferable to two independent clarification records. Clients can collapse notices that point to an already-rendered card.

Failure behavior users can act on

Failure	Internal state	User-visible response
Translation unsupported	Clarification unaffected	Keep original visible; offer clarification
Notification definitely rejected	`notice: failed`	Show “Request saved; notification not sent” and a retry action
Notification outcome unknown	`notice: uncertain`	Show “Request saved; delivery unconfirmed” rather than retrying silently
Source message edited	`superseded`	Link to the new revision and offer a new request
Non-author attempts to answer	No state change	Explain that only the original author can confirm intent
Author deletes the source	Close or supersede according to policy	Remove quoted content and explain that the source is unavailable
Request contains harassment	Moderation path	Preserve access controls and allow reporting; translation is not moderation

Two privacy rules deserve particular attention:

Do not copy private message bodies into notifications that have broader visibility.
Recheck thread membership when reading or answering a clarification. Possessing a clarification ID must not grant access to its source conversation.

The engineering judgment that remains valuable

It is easy to frame multilingual tooling as a test of whether a developer knows enough languages. That is not the most useful question.

The durable skill is deciding where certainty comes from:

The translation feature can provide a readable rendering.
The application can preserve identity, revision, and delivery state.
The original author can confirm intent.
A moderator can decide whether behavior violates community rules.

Those responsibilities should not collapse into one “smart” message box. Making them visible helps users name uncertainty without feeling that they have failed a language test.

Release verification checklist

Before shipping, verify the complete social-messaging flow:

[ ] The original message remains accessible beside any translation.
[ ] Translation is user-invoked and enabled only for a verified deployment configuration.
[ ] Unsupported content or language combinations have a visible fallback.
[ ] Clarification requests store the source message ID and revision.
[ ] Only the original author can resolve a request.
[ ] Editing or deleting the source invalidates open requests according to policy.
[ ] A failed notification does not delete the saved request.
[ ] An uncertain notification is not retried automatically.
[ ] Database writes use conditional updates to prevent double resolution.
[ ] Thread authorization is checked when creating, reading, and answering requests.
[ ] Abuse reports remain separate from translation and clarification.
[ ] Clients do not treat translated notification text as protocol data.

A multilingual community does not need to pretend every sentence has one mechanically recoverable meaning. It needs a reliable way to move from readable to confirmed when the distinction matters.

Disclosure: I have a content relationship with Tencent RTC. Official Tencent RTC documentation was used as the implementation reference for the product-specific portions of this tutorial.

Join the Call Even When Beauty AR Fails: Build a Browser Preflight Gate

LunarDrift — Wed, 14 Oct 2026 17:10:15 +0000

A Beauty AR demo usually proves one thing: an effect can run on the developer’s device.

A production join flow has a harder contract. The user still needs to enter the call if effect initialization times out, the GPU context is lost, a low-end device cannot sustain processing, or an asset fails to load.

That distinction helps clarify the role of “AI in the browser.” Real-time computer vision can produce useful beauty filters, makeup, segmentation, avatars, and gesture-driven effects. It cannot decide how much delay is acceptable, whether an altered image may be published without confirmation, or what the application should do when processing fails. Those remain product and engineering decisions.

In this tutorial, we will build a preflight gate with one invariant:

Beauty AR is a candidate output until it has produced frames and the user explicitly chooses to publish it.

If the candidate fails, the clean camera remains available. The call does not become dependent on the effect.

The workflow we want

The browser join sequence will be:

Acquire the camera.
Show the clean preview.
Prepare a Beauty AR candidate off-air.
Verify that the candidate is producing frames before a deadline.
Let the user choose Join with effect or Join without effect.
Publish only the selected stream.
If the live effect later becomes unhealthy, attempt to replace it with the clean stream.

This is deliberately different from testing whether an API call resolved. A resolved initialization promise does not prove that useful video is reaching the preview.

Tencent RTC’s Beauty AR overview describes real-time capabilities including beauty filters, makeup, stickers, virtual backgrounds, avatars, gesture recognition, and image or video enhancement. Its low-end device optimization guide recommends adapting effects to device tiers, using appropriate performance modes, avoiding expensive segmentation or 3D/GAN effects where necessary, and controlling resolution and frame rate.

Our controller turns those recommendations into an application-level join policy without inventing a universal definition of a “fast device.”

Model the states users can actually encounter

A boolean such as beautyEnabled cannot distinguish loading from failure, qualification, publication, or recovery.

Use explicit phases instead:

type Phase =
  | "idle"
  | "acquiring-camera"
  | "camera-ready"
  | "preparing-effect"
  | "qualifying-effect"
  | "ready-clean"
  | "ready-effect"
  | "publishing"
  | "live-clean"
  | "live-effect"
  | "blocked";

type ViewState = {
  phase: Phase;
  notice?: string;
};

These states produce a straightforward UI contract:

Phase	User-visible behavior
`acquiring-camera`	Disable join and show camera setup progress
`camera-ready`	Show the clean preview
`preparing-effect`	Keep the clean preview visible; allow cancellation
`qualifying-effect`	Indicate that the effect is being checked
`ready-clean`	Enable clean join and explain why the effect is unavailable, if relevant
`ready-effect`	Show both join choices; do not select the effect silently
`publishing`	Prevent duplicate join actions
`live-clean` / `live-effect`	Display which output is currently being sent
`blocked`	Explain the camera or publication failure and offer a relevant retry

The important emotional detail is that “your device could not run this effect” should not be presented as “your device cannot join.” Those are separate capabilities.

Create the reproducible project

Start with a framework-independent TypeScript core. It can later sit behind React, Vue, or another UI.

mkdir beauty-preflight
cd beauty-preflight
npm init -y
npm install -D typescript vitest @types/node
npx tsc --init

Add these scripts to package.json:

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

For deterministic tests, the core uses a small Stream value rather than requiring real browser media objects:

// src/preflight.ts
export type Stream = { id: string };

export type EffectProfile = {
  id: string;
  allowSegmentation: boolean;
  allow3D: boolean;
  allowGAN: boolean;
};

export interface CameraPort {
  open(): Promise<Stream>;
  close(stream: Stream): Promise<void>;
}

export interface BeautyPort {
  create(input: Stream, profile: EffectProfile): Promise<Stream>;
  dispose(stream: Stream): Promise<void>;
}

export interface FrameProbe {
  hasProgress(stream: Stream, windowMs: number): Promise<boolean>;
}

export interface PublisherPort {
  publish(stream: Stream): Promise<void>;
  replace(stream: Stream): Promise<void>;
  unpublish(): Promise<void>;
}

export type Phase =
  | "idle"
  | "acquiring-camera"
  | "camera-ready"
  | "preparing-effect"
  | "qualifying-effect"
  | "ready-clean"
  | "ready-effect"
  | "publishing"
  | "live-clean"
  | "live-effect"
  | "blocked";

export type ViewState = {
  phase: Phase;
  notice?: string;
};

export type Policy = {
  prepareDeadlineMs: number;
  qualificationWindowMs: number;
};

CameraPort, BeautyPort, and PublisherPort are application-owned boundaries. They are not names of Tencent RTC APIs. The production adapters should call the documented browser, Beauty AR, and RTC integration surfaces available to your application.

Race the preparation, but clean up the loser

A timeout does not cancel the operation underneath it. If initialization finishes after the application has fallen back, that late result must be disposed rather than attached to the preview.

// src/preflight.ts

type DeadlineResult<T> =
  | { kind: "ok"; value: T }
  | { kind: "error"; error: unknown }
  | { kind: "timeout" };

async function beforeDeadline<T>(
  operation: Promise<T>,
  deadlineMs: number
): Promise<DeadlineResult<T>> {
  let timer: ReturnType<typeof setTimeout> | undefined;

  const timeout = new Promise<DeadlineResult<T>>((resolve) => {
    timer = setTimeout(() => resolve({ kind: "timeout" }), deadlineMs);
  });

  const settled: Promise<DeadlineResult<T>> = operation.then(
    (value) => ({ kind: "ok", value }),
    (error) => ({ kind: "error", error })
  );

  const result = await Promise.race([settled, timeout]);
  if (timer) clearTimeout(timer);
  return result;
}

The deadline is an application policy, not a Tencent RTC performance guarantee. Choose it from your join experience requirements and verify it on representative devices.

Implement the preflight coordinator

The coordinator retains the clean camera while the effect is prepared. An incrementing epoch invalidates callbacks from cancelled or superseded attempts.

// src/preflight.ts

export class BeautyPreflight {
  private state: ViewState = { phase: "idle" };
  private epoch = 0;
  private raw?: Stream;
  private candidate?: Stream;

  constructor(
    private readonly camera: CameraPort,
    private readonly beauty: BeautyPort,
    private readonly probe: FrameProbe,
    private readonly publisher: PublisherPort,
    private readonly policy: Policy,
    private readonly onState: (state: ViewState) => void
  ) {}

  get snapshot(): ViewState {
    return this.state;
  }

  private transition(state: ViewState): void {
    this.state = state;
    this.onState(state);
  }

  async start(profile: EffectProfile): Promise<void> {
    const attempt = ++this.epoch;
    this.transition({ phase: "acquiring-camera" });

    let raw: Stream;
    try {
      raw = await this.camera.open();
    } catch {
      if (attempt !== this.epoch) return;
      this.transition({
        phase: "blocked",
        notice: "Camera access failed. Check permission or device availability."
      });
      return;
    }

    if (attempt !== this.epoch) {
      await this.camera.close(raw);
      return;
    }

    this.raw = raw;
    this.transition({ phase: "camera-ready" });
    this.transition({ phase: "preparing-effect" });

    const pending = this.beauty.create(raw, profile);
    const prepared = await beforeDeadline(
      pending,
      this.policy.prepareDeadlineMs
    );

    if (prepared.kind === "timeout") {
      // The operation may still resolve. Dispose that late candidate.
      void pending
        .then((lateStream) => this.beauty.dispose(lateStream))
        .catch(() => undefined);

      if (attempt === this.epoch) {
        this.transition({
          phase: "ready-clean",
          notice: "The effect took too long to prepare. You can still join normally."
        });
      }
      return;
    }

    if (prepared.kind === "error") {
      if (attempt === this.epoch) {
        this.transition({
          phase: "ready-clean",
          notice: "The effect could not be loaded. You can still join normally."
        });
      }
      return;
    }

    const candidate = prepared.value;

    if (attempt !== this.epoch) {
      await this.beauty.dispose(candidate);
      return;
    }

    this.candidate = candidate;
    this.transition({ phase: "qualifying-effect" });

    let healthy = false;
    try {
      healthy = await this.probe.hasProgress(
        candidate,
        this.policy.qualificationWindowMs
      );
    } catch {
      healthy = false;
    }

    if (attempt !== this.epoch) {
      await this.beauty.dispose(candidate);
      if (this.candidate === candidate) this.candidate = undefined;
      return;
    }

    if (!healthy) {
      await this.beauty.dispose(candidate);
      this.candidate = undefined;
      this.transition({
        phase: "ready-clean",
        notice: "The effect preview stopped producing frames. Clean video is available."
      });
      return;
    }

    this.transition({ phase: "ready-effect" });
  }

  async chooseClean(): Promise<void> {
    ++this.epoch;

    const oldCandidate = this.candidate;
    this.candidate = undefined;

    if (oldCandidate) await this.beauty.dispose(oldCandidate);

    if (this.raw) {
      this.transition({ phase: "ready-clean" });
    }
  }

  async join(useEffect: boolean): Promise<void> {
    if (!this.raw) {
      this.transition({
        phase: "blocked",
        notice: "The camera is not ready."
      });
      return;
    }

    if (useEffect && this.state.phase !== "ready-effect") {
      this.transition({
        phase: "ready-clean",
        notice: "The requested effect is not ready. Choose clean video or retry it."
      });
      return;
    }

    const previous = this.state;
    const selected = useEffect ? this.candidate : this.raw;

    if (!selected) {
      this.transition({
        phase: "ready-clean",
        notice: "No publishable video is available."
      });
      return;
    }

    this.transition({ phase: "publishing" });

    try {
      await this.publisher.publish(selected);
      this.transition({ phase: useEffect ? "live-effect" : "live-clean" });
    } catch {
      this.transition({
        ...previous,
        notice: "Joining failed. Your preview is still available; retry when ready."
      });
    }
  }

  async recoverToClean(reason: string): Promise<void> {
    if (!this.raw) return;

    try {
      await this.publisher.replace(this.raw);

      if (this.candidate) {
        await this.beauty.dispose(this.candidate);
        this.candidate = undefined;
      }

      this.transition({
        phase: "live-clean",
        notice: `The effect was removed: ${reason}`
      });
    } catch {
      await this.publisher.unpublish().catch(() => undefined);
      this.transition({
        phase: "blocked",
        notice: "Video recovery failed. Video was stopped instead of leaving a frozen effect on-air."
      });
    }
  }
}

recoverToClean() encodes an important trade-off: if replacing an unhealthy effect fails, this implementation stops video rather than intentionally leaving a frozen or corrupted effect output published. Your application can choose a different policy, but it should be explicit and tested.

Test the failures before connecting a camera

Create src/preflight.test.ts:

import { describe, expect, it, vi } from "vitest";
import {
  BeautyPreflight,
  type EffectProfile,
  type Stream
} from "./preflight";

const raw: Stream = { id: "raw" };
const effected: Stream = { id: "effected" };

const profile: EffectProfile = {
  id: "conservative",
  allowSegmentation: false,
  allow3D: false,
  allowGAN: false
};

function deferred<T>() {
  let resolve!: (value: T) => void;
  let reject!: (error: unknown) => void;
  const promise = new Promise<T>((res, rej) => {
    resolve = res;
    reject = rej;
  });
  return { promise, resolve, reject };
}

function fixture(overrides: Record<string, unknown> = {}) {
  const states: string[] = [];

  const camera = {
    open: vi.fn().mockResolvedValue(raw),
    close: vi.fn().mockResolvedValue(undefined)
  };

  const beauty = {
    create: vi.fn().mockResolvedValue(effected),
    dispose: vi.fn().mockResolvedValue(undefined)
  };

  const probe = {
    hasProgress: vi.fn().mockResolvedValue(true)
  };

  const publisher = {
    publish: vi.fn().mockResolvedValue(undefined),
    replace: vi.fn().mockResolvedValue(undefined),
    unpublish: vi.fn().mockResolvedValue(undefined)
  };

  Object.assign({ camera, beauty, probe, publisher }, overrides);

  const controller = new BeautyPreflight(
    camera,
    beauty,
    probe,
    publisher,
    { prepareDeadlineMs: 20, qualificationWindowMs: 10 },
    (state) => states.push(state.phase)
  );

  return { controller, camera, beauty, probe, publisher, states };
}

describe("BeautyPreflight", () => {
  it("keeps clean join available when effect creation fails", async () => {
    const f = fixture();
    f.beauty.create.mockRejectedValueOnce(new Error("asset failed"));

    await f.controller.start(profile);

    expect(f.controller.snapshot.phase).toBe("ready-clean");
    await f.controller.join(false);
    expect(f.publisher.publish).toHaveBeenCalledWith(raw);
  });

  it("rejects an effect that initializes but produces no frames", async () => {
    const f = fixture();
    f.probe.hasProgress.mockResolvedValueOnce(false);

    await f.controller.start(profile);

    expect(f.beauty.dispose).toHaveBeenCalledWith(effected);
    expect(f.controller.snapshot.phase).toBe("ready-clean");
  });

  it("disposes an effect that resolves after the deadline", async () => {
    const late = deferred<Stream>();
    const f = fixture();
    f.beauty.create.mockReturnValueOnce(late.promise);

    await f.controller.start(profile);
    expect(f.controller.snapshot.phase).toBe("ready-clean");

    late.resolve(effected);
    await vi.waitFor(() => {
      expect(f.beauty.dispose).toHaveBeenCalledWith(effected);
    });
  });

  it("does not publish an effect merely because it is ready", async () => {
    const f = fixture();

    await f.controller.start(profile);

    expect(f.controller.snapshot.phase).toBe("ready-effect");
    expect(f.publisher.publish).not.toHaveBeenCalled();

    await f.controller.join(true);
    expect(f.publisher.publish).toHaveBeenCalledWith(effected);
  });

  it("falls back to clean video when a live effect becomes unhealthy", async () => {
    const f = fixture();

    await f.controller.start(profile);
    await f.controller.join(true);
    await f.controller.recoverToClean("frame processing stalled");

    expect(f.publisher.replace).toHaveBeenCalledWith(raw);
    expect(f.controller.snapshot.phase).toBe("live-clean");
  });
});

Run the suite:

npm test

These tests verify authority as well as mechanics. The effect can become eligible for publication, but only join(true) can publish it.

Connect frame qualification to the browser

A production FrameProbe should observe the output users will see—not only the input camera and not only a successful initialization callback.

Where supported by your browser targets, a video-element adapter can observe presented frames with requestVideoFrameCallback. Keep that browser-specific code outside the state machine:

export class VideoElementProbe {
  constructor(
    private readonly resolveVideo: (stream: Stream) => HTMLVideoElement
  ) {}

  async hasProgress(stream: Stream, windowMs: number): Promise<boolean> {
    const video = this.resolveVideo(stream);

    if (!("requestVideoFrameCallback" in video)) {
      // Do not pretend unsupported observation is a successful check.
      return false;
    }

    return new Promise<boolean>((resolve) => {
      let frames = 0;
      let finished = false;

      const finish = (result: boolean) => {
        if (finished) return;
        finished = true;
        resolve(result);
      };

      const onFrame = () => {
        frames += 1;
        if (frames >= 2) return finish(true);
        video.requestVideoFrameCallback(onFrame);
      };

      video.requestVideoFrameCallback(onFrame);
      setTimeout(() => finish(false), windowMs);
    });
  }
}

The count above is an example liveness rule for this tutorial, not a universal quality threshold. A production policy may also consider frame spacing, sustained output, application responsiveness, and visibility state.

Do not qualify an effect while the tab is hidden and then treat that result as representative. Pause the attempt or restart qualification when the document becomes visible again.

CPU/GPU policy: use capability hints, then verify output

Browser capability flags are useful inputs, but poor final authorities.

For example:

A GPU interface being available does not prove enough headroom for a particular effect.
CPU core count does not describe thermal throttling or competing workloads.
A device model or user-agent string does not reveal the current session’s resource pressure.
Successful initialization does not prove sustained frame delivery.

Use a two-stage decision:

Stage 1: Select a conservative candidate profile

An application-owned profile can restrict expensive categories:

const conservativeProfile: EffectProfile = {
  id: "conservative",
  allowSegmentation: false,
  allow3D: false,
  allowGAN: false
};

For constrained device tiers, follow the official optimization guidance: choose an appropriate performance mode, avoid expensive segmentation or 3D/GAN effects, and control capture resolution and frame rate. Do not copy arbitrary thresholds from another product and call them device tiers.

Stage 2: Verify the candidate in the current session

Regardless of the initial profile, require actual output progress. Continue monitoring after publication so thermal pressure, GPU context loss, or backgrounding can trigger recoverToClean().

This creates graceful degradation rather than a binary “AI-capable” label:

Requested effect profile.
Simpler effect profile, if the user agrees.
Clean video.
Video stopped if clean recovery itself cannot be published safely.

Automatic fallback between visibly different effects should also be disclosed. “We silently changed your appearance” is not an acceptable interpretation of graceful degradation.

React should render the state, not reconstruct it

A React component can subscribe to ViewState and map it to controls:

function JoinControls({
  state,
  join,
  chooseClean
}: {
  state: ViewState;
  join: (withEffect: boolean) => void;
  chooseClean: () => void;
}) {
  const canJoinClean =
    state.phase === "ready-clean" || state.phase === "ready-effect";

  return (
    <section aria-live="polite">
      {state.notice && <p>{state.notice}</p>}

      <button disabled={!canJoinClean} onClick={() => join(false)}>
        Join without effect
      </button>

      <button
        disabled={state.phase !== "ready-effect"}
        onClick={() => join(true)}
      >
        Join with effect
      </button>

      {(state.phase === "preparing-effect" ||
        state.phase === "qualifying-effect") && (
        <button onClick={chooseClean}>Skip effect</button>
      )}
    </section>
  );
}

Avoid deriving readiness from a collection of React booleans such as loading, enabled, and failed. Let the coordinator own legal transitions; let React render them.

Failure drills to run on real devices

Unit tests cannot reproduce every browser and hardware behavior. Before release, perform these drills with representative devices and workloads.

Camera permission is denied

Expected result: no effect initialization starts, no join button implies video is ready, and the UI explains how to retry.

Effect assets fail to load

Expected result: the clean preview remains visible and clean join is enabled. Repeated automatic downloads should not trap the user in setup.

The preparation deadline expires

Expected result: the UI moves to ready-clean. If initialization later completes, its output is disposed and never replaces the preview.

The user skips while initialization is pending

Expected result: the epoch invalidates the pending result. A late callback cannot re-enable or publish the effect.

The candidate initializes but frames do not advance

Expected result: qualification fails, resources are disposed, and the clean stream remains available.

The tab is backgrounded during qualification

Expected result: do not certify that run. Pause or restart qualification after visibility returns.

The live effect stalls

Expected result: replace it with the clean stream and show a neutral explanation. If replacement fails, follow the declared stop-video or reconnect policy.

Publishing fails after a successful preview

Expected result: retain the local preview and offer a retry. Preview readiness and RTC publication are separate states.

Release verification checklist

Before shipping, verify that:

[ ] The clean camera is acquired independently of Beauty AR initialization.
[ ] No effect output is published before explicit user confirmation.
[ ] A deadline leads to clean join rather than an endless spinner.
[ ] Late initialization results are disposed.
[ ] Qualification observes processed output frames, not merely input frames.
[ ] Hidden-tab qualification is paused or invalidated.
[ ] Low-end profiles avoid effects your device policy classifies as too expensive.
[ ] Resolution and frame-rate choices are tested on representative hardware.
[ ] Runtime stalls trigger a clean-output recovery path.
[ ] Failed stream replacement has a defined, user-visible outcome.
[ ] Logs distinguish camera failure, effect failure, qualification failure, and publication failure.
[ ] The user can always tell whether clean or altered video is being sent.

Browser-based computer vision is a demonstrated capability. Reliable participation is the product contract. Keeping those ideas separate lets developers use Beauty AR without making a user’s ability to join depend on an effect—or making hardware limitations feel like personal failure.

Implementation references and disclosure

Implementation guidance was checked against the official Tencent RTC Beauty AR overview and Low-End Device Performance Optimization Practice Guide.

Disclosure: I’m writing in collaboration with Tencent RTC, and I used official Tencent RTC documentation as the implementation reference for this tutorial.

A Pet Photo Is Not Posted Until It Has a Receipt: Build a Durable Community Outbox

LunarDrift — Sun, 11 Oct 2026 17:14:27 +0000

A community prompt such as “show us your pet” sounds almost too simple to architect: choose a photo, add a caption, and post it.

Then a mobile connection drops at exactly the wrong moment.

The author presses Post again. The first request may have succeeded, the announcement may have been delivered, and the browser has no receipt. A convincing demo retries everything. A reliable community product must distinguish saved content, message delivery, and unknown outcomes.

In this tutorial, we will build a durable TypeScript submission coordinator for a rich-media community. It guarantees one canonical post per client operation, makes announcement failures visible, and refuses to hide an uncertain delivery behind an automatic retry.

Choose the correct source of truth

There are two reasonable ways to implement a community photo prompt:

Design	Good fit	Main trade-off
Send the photo directly as a chat message	Casual, ephemeral conversation	Retrying safely depends on the downstream messaging contract
Save a canonical post, then announce it in chat	Moderated, editable, or long-lived community content	Requires application storage and two visible states

We will use the second design.

Tencent RTC's Social Messaging solution covers scenarios including group discussions, large communities, and rich-media interaction. Our application will use that messaging layer for the community announcement, while its own database remains authoritative for the submitted post.

This distinction gives us an honest invariant:

A failed announcement must not erase a saved post, and retrying an announcement must never create a second canonical post.

It does not let us claim exactly-once message delivery. If the process crashes after an external send succeeds but before its receipt is persisted, the result is uncertain. We will model that uncertainty explicitly.

The two related state machines

The browser owns media preparation:

draft
  └─> uploading ──> ready ──> submitting
         │                       │
         └─> upload_failed       ├─> accepted
                                 └─> blocked

The server owns the canonical post and announcement:

content:  visible | blocked

delivery:
  queued ──> sending ──> sent
                │
                ├─> failed
                └─> unknown   (detected after an interrupted process)

unknown is intentionally different from failed:

failed means the adapter returned an error before a success receipt was recorded.
unknown means the application cannot prove whether the external announcement happened.

Automatic retry is reasonable for some known failures. It is unsafe for an unknown outcome unless duplicate announcements are acceptable or the downstream integration supplies an idempotency contract you have verified.

Create the reproducible project

Use Node.js 20 or later:

mkdir durable-community-post
cd durable-community-post
npm init -y
npm install --save-dev typescript tsx @types/node
mkdir src test
npm pkg set type=module
npm pkg set scripts.test="tsx --test"

Create src/coordinator.ts:

export type DeliveryState =
  | "not_applicable"
  | "queued"
  | "sending"
  | "sent"
  | "failed"
  | "unknown";

export type ContentState = "visible" | "blocked";

export interface Submission {
  operationId: string;
  authorId: string;
  text: string;
  mediaKey: string;
  altText: string;
  hasPostingRights: boolean;
}

export interface Post {
  postId: string;
  operationId: string;
  fingerprint: string;
  authorId: string;
  text: string;
  mediaKey: string;
  altText: string;
  contentState: ContentState;
  deliveryState: DeliveryState;
  messageId?: string;
  reason?: string;
}

export interface PostRepository {
  // Production implementations must make this atomic.
  create(candidate: Post): Promise<{ post: Post; created: boolean }>;
  getByPostId(postId: string): Promise<Post | undefined>;
  save(post: Post): Promise<void>;
  listSending(): Promise<Post[]>;
}

export interface CommunityMessenger {
  announce(post: Post): Promise<{ messageId: string }>;
}

function fingerprint(input: Submission): string {
  // A fixed tuple avoids depending on object-property order.
  return JSON.stringify([
    input.authorId,
    input.text,
    input.mediaKey,
    input.altText,
    input.hasPostingRights
  ]);
}

function buildPost(input: Submission): Post {
  const blockedReason = !input.hasPostingRights
    ? "posting_rights_not_confirmed"
    : input.altText.trim().length === 0
      ? "alt_text_required"
      : undefined;

  return {
    postId: `post-${input.operationId}`,
    operationId: input.operationId,
    fingerprint: fingerprint(input),
    authorId: input.authorId,
    text: input.text,
    mediaKey: input.mediaKey,
    altText: input.altText,
    contentState: blockedReason ? "blocked" : "visible",
    deliveryState: blockedReason ? "not_applicable" : "queued",
    reason: blockedReason
  };
}

export class SubmissionCoordinator {
  constructor(
    private readonly repository: PostRepository,
    private readonly messenger: CommunityMessenger
  ) {}

  async submit(input: Submission): Promise<Post> {
    const candidate = buildPost(input);
    const result = await this.repository.create(candidate);

    if (result.post.fingerprint !== candidate.fingerprint) {
      throw new Error("operation_id_reused_with_different_content");
    }

    // A repeated HTTP request returns the existing outcome. It does not
    // silently repeat the external announcement.
    if (!result.created) return result.post;

    if (result.post.contentState === "blocked") return result.post;

    return this.deliver(result.post);
  }

  async retryAnnouncement(
    postId: string,
    acceptDuplicateRisk = false
  ): Promise<Post> {
    const post = await this.repository.getByPostId(postId);
    if (!post) throw new Error("post_not_found");

    if (post.deliveryState === "sent") return post;

    if (post.deliveryState === "unknown" && !acceptDuplicateRisk) {
      throw new Error("delivery_unknown_requires_explicit_decision");
    }

    if (!['failed', 'unknown', 'queued'].includes(post.deliveryState)) {
      throw new Error(`cannot_retry_from_${post.deliveryState}`);
    }

    return this.deliver(post);
  }

  async recoverInterruptedDeliveries(): Promise<number> {
    const interrupted = await this.repository.listSending();

    for (const post of interrupted) {
      post.deliveryState = "unknown";
      post.reason = "process_interrupted_during_announcement";
      await this.repository.save(post);
    }

    return interrupted.length;
  }

  private async deliver(post: Post): Promise<Post> {
    post.deliveryState = "sending";
    post.reason = undefined;
    await this.repository.save(post);

    try {
      const receipt = await this.messenger.announce(post);
      post.deliveryState = "sent";
      post.messageId = receipt.messageId;
      await this.repository.save(post);
      return post;
    } catch (error) {
      post.deliveryState = "failed";
      post.reason = String(error);
      await this.repository.save(post);
      return post;
    }
  }
}

export class MemoryPostRepository implements PostRepository {
  private readonly byOperation = new Map<string, Post>();

  async create(candidate: Post): Promise<{ post: Post; created: boolean }> {
    const existing = this.byOperation.get(candidate.operationId);
    if (existing) return { post: structuredClone(existing), created: false };

    this.byOperation.set(candidate.operationId, structuredClone(candidate));
    return { post: structuredClone(candidate), created: true };
  }

  async getByPostId(postId: string): Promise<Post | undefined> {
    const post = [...this.byOperation.values()].find(p => p.postId === postId);
    return post ? structuredClone(post) : undefined;
  }

  async save(post: Post): Promise<void> {
    this.byOperation.set(post.operationId, structuredClone(post));
  }

  async listSending(): Promise<Post[]> {
    return [...this.byOperation.values()]
      .filter(post => post.deliveryState === "sending")
      .map(post => structuredClone(post));
  }
}

The operationId should be generated once when the browser creates the draft and persisted with that draft. Refreshes and request retries must reuse it. Editing the content should create a new revision or operation rather than silently reusing the old key.

Verify the dangerous paths

Create test/coordinator.test.ts:

import assert from "node:assert/strict";
import test from "node:test";
import {
  CommunityMessenger,
  MemoryPostRepository,
  Submission,
  SubmissionCoordinator
} from "../src/coordinator.js";

const validPost: Submission = {
  operationId: "browser-7-draft-41",
  authorId: "member-12",
  text: "Mochi debugging the cardboard box",
  mediaKey: "uploads/member-12/mochi.jpg",
  altText: "A tabby cat sitting inside a cardboard box",
  hasPostingRights: true
};

test("a repeated submission does not announce twice", async () => {
  const repository = new MemoryPostRepository();
  let announcements = 0;

  const messenger: CommunityMessenger = {
    async announce() {
      announcements += 1;
      return { messageId: "message-1" };
    }
  };

  const coordinator = new SubmissionCoordinator(repository, messenger);

  const first = await coordinator.submit(validPost);
  const repeated = await coordinator.submit(validPost);

  assert.equal(first.deliveryState, "sent");
  assert.equal(repeated.postId, first.postId);
  assert.equal(announcements, 1);
});

test("the same operation ID cannot identify changed content", async () => {
  const repository = new MemoryPostRepository();
  const messenger: CommunityMessenger = {
    async announce() {
      return { messageId: "message-1" };
    }
  };

  const coordinator = new SubmissionCoordinator(repository, messenger);
  await coordinator.submit(validPost);

  await assert.rejects(
    coordinator.submit({ ...validPost, text: "Changed caption" }),
    /operation_id_reused_with_different_content/
  );
});

test("a failed announcement leaves the canonical post retryable", async () => {
  const repository = new MemoryPostRepository();
  let attempts = 0;

  const messenger: CommunityMessenger = {
    async announce() {
      attempts += 1;
      if (attempts === 1) throw new Error("temporary_delivery_failure");
      return { messageId: "message-after-retry" };
    }
  };

  const coordinator = new SubmissionCoordinator(repository, messenger);

  const failed = await coordinator.submit(validPost);
  assert.equal(failed.contentState, "visible");
  assert.equal(failed.deliveryState, "failed");

  const retried = await coordinator.retryAnnouncement(failed.postId);
  assert.equal(retried.deliveryState, "sent");
  assert.equal(attempts, 2);
});

test("missing posting confirmation blocks publication", async () => {
  const repository = new MemoryPostRepository();
  let announcements = 0;

  const coordinator = new SubmissionCoordinator(repository, {
    async announce() {
      announcements += 1;
      return { messageId: "should-not-exist" };
    }
  });

  const result = await coordinator.submit({
    ...validPost,
    hasPostingRights: false
  });

  assert.equal(result.contentState, "blocked");
  assert.equal(result.reason, "posting_rights_not_confirmed");
  assert.equal(announcements, 0);
});

Run the suite:

npm test

The tests prove four separate properties:

A repeated request returns the same canonical post.
An operation ID cannot be reassigned to different content.
A delivery failure does not discard the post.
A blocked submission never reaches the messaging adapter.

Replace memory with an atomic database operation

The in-memory repository is only a reproducible test adapter. In production, create() must atomically enforce the operation ID.

A relational table can start with this shape:

CREATE TABLE community_posts (
  post_id         TEXT PRIMARY KEY,
  operation_id    TEXT NOT NULL UNIQUE,
  fingerprint     TEXT NOT NULL,
  author_id       TEXT NOT NULL,
  text_body       TEXT NOT NULL,
  media_key       TEXT NOT NULL,
  alt_text        TEXT NOT NULL,
  content_state   TEXT NOT NULL CHECK (content_state IN ('visible', 'blocked')),
  delivery_state  TEXT NOT NULL CHECK (
    delivery_state IN (
      'not_applicable', 'queued', 'sending', 'sent', 'failed', 'unknown'
    )
  ),
  message_id      TEXT,
  reason          TEXT,
  created_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  updated_at      TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
);

On an operation-ID conflict, read the existing row and compare its fingerprint. Do not treat every conflict as success: accepting the same key with different content would make receipts ambiguous.

Media upload also needs its own durable identity. mediaKey should refer to a finalized server-recognized asset, not a browser object URL. If upload fails, keep the browser draft in upload_failed; do not submit a post whose attachment only exists in local memory.

Connect the coordinator to Tencent RTC Social Messaging

Keep product-specific code behind CommunityMessenger:

class TencentCommunityMessenger implements CommunityMessenger {
  async announce(post: Post): Promise<{ messageId: string }> {
    // 1. Construct the approved community announcement presentation.
    // 2. Send it through the Tencent RTC messaging integration selected
    //    for your application.
    // 3. Return only after obtaining the integration's success receipt.
    //
    // Use the exact SDK and message-type documentation for your target
    // platform here rather than guessing an API name or payload shape.
    throw new Error("adapter_not_configured");
  }
}

The announcement can present the image and caption or point members to the canonical post, depending on your product design. The important boundary is that the adapter does not decide whether a post exists, whether the author confirmed posting rights, or whether an uncertain send may be repeated.

Those are application decisions.

If your multilingual community wants on-demand caption translation, check the official TUIChat message translation documentation before including it in acceptance criteria. Supported content types, languages, and edition limits must be verified for the intended deployment. Translation should be an optional reading aid; it should not alter the saved caption, alt text, operation fingerprint, or moderation record.

User-visible behavior for each failure

A state machine only helps if users can understand its outcomes.

Condition	UI behavior	Safe action
Media upload failed	Keep the draft and show the failed attachment	Retry upload
Post blocked by policy	Explain the actionable reason	Edit or cancel
Post saved, announcement failed	Show “Post saved; community announcement delayed”	Retry announcement
Delivery outcome unknown	Show “We could not confirm the announcement”	Check the channel or explicitly accept duplicate risk
Operation ID reused with changed content	Reject as a client conflict	Create a new operation ID
Announcement sent	Show the canonical post and receipt-backed status	No retry button

Do not show “Post failed” when the canonical post is safely stored. That wording encourages users to resubmit and creates duplicates at the product level.

Crash drill: the gap no unit retry can remove

There is an unavoidable sequence to test:

Persist deliveryState = "sending".
Send the community announcement.
Receive success from the messaging integration.
Crash before persisting deliveryState = "sent".

After restart, call recoverInterruptedDeliveries(). Any row left in sending becomes unknown, not failed.

From there, choose deliberately:

Check before retrying if your integration and application can locate the previous announcement reliably.
Allow a deliberate retry if duplicate announcements are an acceptable trade-off.
Escalate to a moderator for high-visibility community announcements.
Do not retry automatically merely because a timer expired.

A transactional outbox improves database-side reliability, but it cannot create exactly-once behavior across an external system unless the complete downstream contract supports compatible idempotency or deduplication.

Pre-release verification checklist

Run these checks with the real database and messaging adapter:

[ ] Double-clicking Post produces one canonical database row.
[ ] Replaying the same HTTP request returns the same post ID.
[ ] Reusing an operation ID with changed content returns a conflict.
[ ] A failed media upload never starts post submission.
[ ] Missing alt text or posting-rights confirmation prevents announcement.
[ ] A known adapter failure leaves the post in failed and permits a controlled retry.
[ ] Killing the process during sending produces unknown after recovery.
[ ] Unknown delivery is not retried without an explicit decision.
[ ] The UI distinguishes “saved but unannounced” from “not saved.”
[ ] Reports, deletion, and moderator actions target the canonical post ID.
[ ] Logs contain operation and post IDs, but do not expose private media URLs or unnecessary message content.

The larger lesson is not that a playful community feature needs enterprise ceremony. It is that friendliness does not remove distributed-system ambiguity. A durable post ID, an honest receipt, and a visible unknown state let the community remain casual without making its implementation careless.

Disclosure: I created this article as part of a content collaboration connected to Tencent RTC. Official Tencent RTC documentation was used as the implementation reference; the state model and sample application architecture are original tutorial material.

Never Execute the Translation: Build Language-Safe Slash Commands for Tencent RTC Chat

LunarDrift — Wed, 07 Oct 2026 17:10:14 +0000

A slash command looks like ordinary text, but it is not ordinary text.

Consider this message in a multilingual community:

/report msg_481 "personal attack in the second paragraph"

The sender expects an action. Other participants may need a translation. A moderator needs both the original wording and enough context to make a decision.

The tension is that the same text now has two roles: human-readable language and machine-readable instructions. If translated or reformatted text is sent back through the command parser, a display feature can accidentally become an execution path.

This is similar to a recurring lesson from shell scripting: text that looks harmless can acquire operational meaning when it crosses into the wrong interpreter. The practical response is not “parse more cleverly.” It is to establish a boundary:

Only an authenticated, original message can create a command. Translation is presentation state, never command input.

In this tutorial, we will build that boundary for a Tencent RTC Social Messaging application. The example command creates a moderation report, but it does not automatically punish another user. A human reviewer retains authority over the outcome.

The behavior we want

Our command contract is deliberately narrow:

/report <message-id> "<reason>"

A reliable implementation must satisfy these rules:

Only original, user-authored text is eligible for parsing.
The syntax is exact and independent of the user's display language.
The target message must be visible to the reporter in the same room.
Duplicate delivery must not create duplicate reports.
Queue failure must produce a retryable state, not a fake success.
Translation may be displayed on demand, but it cannot create or modify the report.
A moderator—not the parser or translation layer—resolves the report.

That gives us three separate concerns:

Original chat event ──> command parser ──> report queue
        │                                      │
        └──> TUIChat display/translation       └──> human review

Notice the missing arrow: translated display text never returns to the command parser.

Create the TypeScript project

mkdir language-safe-chat-commands
cd language-safe-chat-commands
npm init -y
npm install --save-dev typescript tsx vitest @types/node
npx tsc --init
mkdir src

Add these scripts to package.json:

{
  "scripts": {
    "test": "vitest run",
    "check": "tsc --noEmit"
  }
}

The core will not depend on a particular UI callback or an invented SDK method. Instead, it accepts trusted application events through a small interface. That makes the dangerous behavior testable before it is connected to a live room.

Represent provenance explicitly

Create src/report-service.ts:

export type MessageProvenance = 'original' | 'derived';

export interface ChatText {
  messageId: string;
  roomId: string;
  authorId: string;
  contentType: 'text' | 'other';
  text: string;
  provenance: MessageProvenance;
}

export interface ReportCommand {
  targetMessageId: string;
  reason: string;
}

interface ReportBase {
  source: ChatText;
  command: ReportCommand;
  attempts: number;
}

export type ReportState =
  | { status: 'received'; source: ChatText }
  | {
      status: 'rejected';
      source: ChatText;
      code: 'INVALID_SYNTAX' | 'TARGET_NOT_VISIBLE';
    }
  | (ReportBase & { status: 'queued'; ticketId: string })
  | (ReportBase & { status: 'failed'; code: 'QUEUE_UNAVAILABLE' })
  | (ReportBase & {
      status: 'resolved';
      ticketId: string;
      decision: 'dismissed' | 'actioned';
      reviewerId: string;
    });

export interface TargetPolicy {
  canReport(input: {
    roomId: string;
    reporterId: string;
    targetMessageId: string;
  }): Promise<boolean>;
}

export interface ReportQueue {
  enqueue(input: {
    idempotencyKey: string;
    roomId: string;
    reporterId: string;
    targetMessageId: string;
    originalReason: string;
  }): Promise<{ ticketId: string }>;
}

provenance is not a value that should be trusted from a browser request. Your server-side integration must derive it from the authenticated event path.

For example, a raw message event accepted from your messaging backend can become original. Text created by translation, summarization, previews, or other transformations must be derived—if it enters this service at all.

An even safer design is to keep translated text entirely outside this event model.

Give the command a small grammar

Using text.split(' ') would make quoted reasons unreliable:

/report msg_481 "personal attack"

A split would produce four fragments rather than the three logical fields. Instead, use a narrow grammar that accepts a constrained message ID and a quoted reason.

Add this below the interfaces:

type ParseResult =
  | { kind: 'not-command' }
  | { kind: 'malformed' }
  | { kind: 'valid'; command: ReportCommand };

export function parseReport(text: string): ParseResult {
  // `/reporting` remains ordinary conversation.
  if (!/^\/report(?:\s|$)/u.test(text)) {
    return { kind: 'not-command' };
  }

  const match = text.match(
    /^\/report[ \t]+([A-Za-z0-9_-]{1,64})[ \t]+"((?:\\["\\]|[^"\\]){1,500})"[ \t]*$/u,
  );

  if (!match) {
    return { kind: 'malformed' };
  }

  const [, targetMessageId, escapedReason] = match;
  const reason = escapedReason.replace(/\\(["\\])/gu, '$1').trim();

  if (!reason) {
    return { kind: 'malformed' };
  }

  return {
    kind: 'valid',
    command: { targetMessageId, reason },
  };
}

This parser makes several product decisions explicit:

/report is case-sensitive.
Message IDs have a constrained character set and length.
Reasons must be quoted.
A reason may contain an escaped quote or backslash.
Additional flags are rejected rather than guessed.

These restrictions may feel less convenient than natural-language commands, but they reduce ambiguity at a side-effect boundary.

Process commands through explicit states

Continue in src/report-service.ts:

export class ReportService {
  private readonly states = new Map<string, ReportState>();

  constructor(
    private readonly targets: TargetPolicy,
    private readonly queue: ReportQueue,
  ) {}

  get(messageId: string): ReportState | undefined {
    return this.states.get(messageId);
  }

  async ingest(message: ChatText): Promise<ReportState | undefined> {
    if (message.contentType !== 'text' || message.provenance !== 'original') {
      return undefined;
    }

    const parsed = parseReport(message.text);

    if (parsed.kind === 'not-command') {
      return undefined;
    }

    const existing = this.states.get(message.messageId);
    if (existing) {
      return existing;
    }

    this.states.set(message.messageId, {
      status: 'received',
      source: message,
    });

    if (parsed.kind === 'malformed') {
      const rejected: ReportState = {
        status: 'rejected',
        source: message,
        code: 'INVALID_SYNTAX',
      };
      this.states.set(message.messageId, rejected);
      return rejected;
    }

    const visible = await this.targets.canReport({
      roomId: message.roomId,
      reporterId: message.authorId,
      targetMessageId: parsed.command.targetMessageId,
    });

    if (!visible) {
      const rejected: ReportState = {
        status: 'rejected',
        source: message,
        code: 'TARGET_NOT_VISIBLE',
      };
      this.states.set(message.messageId, rejected);
      return rejected;
    }

    return this.enqueue({
      status: 'failed',
      source: message,
      command: parsed.command,
      attempts: 0,
      code: 'QUEUE_UNAVAILABLE',
    });
  }

  async retry(messageId: string): Promise<ReportState> {
    const current = this.states.get(messageId);

    if (!current || current.status !== 'failed') {
      throw new Error('Only failed reports can be retried');
    }

    return this.enqueue(current);
  }

  resolve(input: {
    messageId: string;
    reviewerId: string;
    decision: 'dismissed' | 'actioned';
  }): ReportState {
    const current = this.states.get(input.messageId);

    if (!current || current.status !== 'queued') {
      throw new Error('Only queued reports can be resolved');
    }

    const resolved: ReportState = {
      ...current,
      status: 'resolved',
      reviewerId: input.reviewerId,
      decision: input.decision,
    };

    this.states.set(input.messageId, resolved);
    return resolved;
  }

  private async enqueue(
    report: Extract<ReportState, { status: 'failed' }>,
  ): Promise<ReportState> {
    const attempts = report.attempts + 1;

    try {
      const result = await this.queue.enqueue({
        idempotencyKey: report.source.messageId,
        roomId: report.source.roomId,
        reporterId: report.source.authorId,
        targetMessageId: report.command.targetMessageId,
        originalReason: report.command.reason,
      });

      const queued: ReportState = {
        status: 'queued',
        source: report.source,
        command: report.command,
        attempts,
        ticketId: result.ticketId,
      };

      this.states.set(report.source.messageId, queued);
      return queued;
    } catch {
      const failed: ReportState = {
        status: 'failed',
        source: report.source,
        command: report.command,
        attempts,
        code: 'QUEUE_UNAVAILABLE',
      };

      this.states.set(report.source.messageId, failed);
      return failed;
    }
  }
}

The in-memory map makes the example easy to reproduce, but it is not sufficient for production durability. Persist report state, and require the queue or database to enforce uniqueness on the idempotency key.

That second constraint matters because a process can crash after the queue accepts a report but before the local state is updated. An in-memory duplicate check cannot cover that interval.

Verify the dangerous paths

Create src/report-service.test.ts:

import { describe, expect, it, vi } from 'vitest';
import {
  type ChatText,
  type ReportQueue,
  ReportService,
  type TargetPolicy,
} from './report-service.js';

const original = (text: string): ChatText => ({
  messageId: 'command-1',
  roomId: 'room-7',
  authorId: 'user-2',
  contentType: 'text',
  provenance: 'original',
  text,
});

const allowed: TargetPolicy = {
  canReport: async () => true,
};

describe('ReportService', () => {
  it('queues a valid command while preserving the original reason', async () => {
    const enqueue = vi.fn(async () => ({ ticketId: 'ticket-9' }));
    const service = new ReportService(allowed, { enqueue });

    const state = await service.ingest(
      original('/report msg_481 "personal attack in paragraph two"'),
    );

    expect(state?.status).toBe('queued');
    expect(enqueue).toHaveBeenCalledWith({
      idempotencyKey: 'command-1',
      roomId: 'room-7',
      reporterId: 'user-2',
      targetMessageId: 'msg_481',
      originalReason: 'personal attack in paragraph two',
    });
  });

  it('does not execute derived or translated text', async () => {
    const enqueue = vi.fn();
    const service = new ReportService(allowed, { enqueue } as ReportQueue);

    const state = await service.ingest({
      ...original('/report msg_481 "translated display text"'),
      provenance: 'derived',
    });

    expect(state).toBeUndefined();
    expect(enqueue).not.toHaveBeenCalled();
  });

  it('does not duplicate a report when an event is delivered twice', async () => {
    const enqueue = vi.fn(async () => ({ ticketId: 'ticket-9' }));
    const service = new ReportService(allowed, { enqueue });
    const message = original('/report msg_481 "reason"');

    await service.ingest(message);
    await service.ingest(message);

    expect(enqueue).toHaveBeenCalledTimes(1);
  });

  it('exposes queue failure and allows an explicit retry', async () => {
    const enqueue = vi
      .fn()
      .mockRejectedValueOnce(new Error('unavailable'))
      .mockResolvedValueOnce({ ticketId: 'ticket-10' });

    const service = new ReportService(allowed, { enqueue });

    const failed = await service.ingest(
      original('/report msg_481 "reason"'),
    );
    expect(failed?.status).toBe('failed');

    const retried = await service.retry('command-1');
    expect(retried.status).toBe('queued');
    expect(enqueue).toHaveBeenCalledTimes(2);
  });

  it('rejects a target the reporter cannot access', async () => {
    const enqueue = vi.fn();
    const denied: TargetPolicy = { canReport: async () => false };
    const service = new ReportService(denied, { enqueue } as ReportQueue);

    const state = await service.ingest(
      original('/report hidden-message "reason"'),
    );

    expect(state).toMatchObject({
      status: 'rejected',
      code: 'TARGET_NOT_VISIBLE',
    });
    expect(enqueue).not.toHaveBeenCalled();
  });
});

Run both checks:

npm test
npm run check

These tests prove the application-level authority boundary. They do not prove that the live integration correctly labels provenance, persists idempotency keys, or keeps translated rendering out of the event stream. Those require integration tests.

Connect the boundary to Tencent RTC Social Messaging

Tencent RTC's Social Messaging solution covers experiences including 1-to-1 chat, group discussion, communities, rich media, and live-room chat. Use the official solution page to select the appropriate messaging surface for your application:

https://trtc.io/solutions/social-messaging

TUIChat also documents on-demand text-message translation. The supported content types, languages, and edition limits are deployment considerations, so verify them against the current official documentation rather than assuming every message can be translated:

https://trtc.io/document/60772

The integration should preserve this direction of data flow:

TUIChat displays the original message.
A user may request the documented translation experience for eligible content.
Translation changes what that user can read; it does not replace the authoritative message event.
Your trusted backend adapter converts an authenticated original message event into ChatText.
ReportService.ingest() classifies and validates it.
The report queue stores the original reason and source message ID.
A moderator reviews the report and records a decision.

Do not attach the parser to rendered DOM text, clipboard text, translated labels, notification previews, or accessibility output. Those surfaces are presentation artifacts and may differ from the original message.

Also avoid inventing a second “translated message” in the room merely to show localized text. If your product deliberately publishes generated text as a new chat message, treat it as a separate derived message and make it ineligible for commands.

What users should see in each state

Internal state is only useful when it produces honest feedback.

State	User-visible behavior
`received`	Brief pending indicator; do not claim success
`rejected / INVALID_SYNTAX`	Show the exact accepted format without attempting a partial command
`rejected / TARGET_NOT_VISIBLE`	Say the message cannot be reported from the current context; do not reveal whether a hidden message exists
`failed / QUEUE_UNAVAILABLE`	Keep the command visible and offer retry; do not say “report submitted”
`queued`	Confirm receipt and provide a reference if your policy permits it
`resolved`	Show only the outcome information your moderation policy allows

Translation failure should be reported separately from command state. A failed translation does not mean the report failed, and a successful translation does not mean the report was accepted.

Failure cases worth drilling in staging

A translated string happens to begin with `/report`

Expected result: it remains display text. No queue call occurs.

Inspect the actual live integration to confirm that translation does not emit another event through the original-message handler.

The sender edits or deletes the command

Choose a policy rather than silently guessing. A defensible default is that a queued moderation report is an immutable record of what was submitted at that time. A later edit can be stored as additional context, but it should not rewrite the original report.

If your product instead allows withdrawal, make withdrawal a separate authenticated operation—not an implication inferred from edited text.

The queue accepts the report and the application crashes

On restart, redelivery may call enqueue again. Verify that the durable queue or database returns the existing record for the same source message ID rather than creating another case.

The target disappears before review

Keep the report and mark the target as unavailable. Deletion may itself be relevant moderation context. Do not automatically resolve the report merely because the current UI can no longer render the target.

A moderator requests a translation

Show the original and translation together. The translated reason can help comprehension, but the reviewer should be able to inspect the source wording and surrounding conversation before deciding.

A malicious client marks its own text as `original`

This is why provenance cannot be a client-controlled boolean. Build ChatText from a verified server-side message path and authenticated identity. Reject direct browser attempts to call the report queue with arbitrary author or room fields.

When slash commands are the wrong interface

A fixed command grammar is not always the best choice. Use this decision framework:

Interface	Best fit	Main trade-off
Fixed slash command	Developer communities, keyboard-heavy workflows, bot integrations	Requires users to learn exact syntax
Report button plus form	General consumer communities and sensitive moderation flows	More UI work, but far less parsing ambiguity
Localized command aliases	Environments where commands must be typed in several languages	Alias collisions and a larger test matrix
Natural-language intent parsing	Low-risk discovery or suggestions	Too ambiguous for direct moderation side effects

For most user-facing moderation systems, a report button with structured fields is safer. The slash command is appropriate when it is intentionally part of the community's interaction model—not merely because parsing text was quicker to demo.

If you do support localized aliases such as multiple words for /report, resolve aliases to a stable command identifier before execution. Keep the target ID and reason structured, and test every alias. Never translate an arbitrary sentence and then ask whether the result resembles a command.

Release verification checklist

Before enabling command processing in a Tencent RTC social-messaging room, verify all of the following:

[ ] Original and translated text are separate presentation states.
[ ] The parser receives authenticated original events, not rendered text.
[ ] Non-text and derived content cannot execute commands.
[ ] Quoted spaces and escaped quotes have automated tests.
[ ] Malformed commands cause no partial side effects.
[ ] The target must belong to a context visible to the reporter.
[ ] Queue idempotency survives process restart and event redelivery.
[ ] Queue failure remains visibly retryable.
[ ] Translation failure does not alter report state.
[ ] Moderators can inspect original wording and relevant context.
[ ] No automated sanction occurs merely because the command parsed.
[ ] Supported translation content, language, and edition requirements have been checked against the current TUIChat documentation.

The useful reframing is that multilingual chat does not have one universal text value. It has original content, translated presentation, machine instructions, and human decisions. Reliability comes from keeping those roles separate rather than asking one string to carry all of them.

Disclosure: I have a content relationship with Tencent RTC. Official Tencent RTC documentation was used as the implementation reference for this article.

Keep the Original in View: Reliable Translation for a Tencent RTC Project-Critique Community

LunarDrift — Mon, 05 Oct 2026 17:12:18 +0000

Building a project showcase is easier than it used to be. Building a community where people can understand and critique that work across languages is still difficult.

That distinction matters. A polished chat demo may translate one sample message correctly, but a real community must answer harder questions:

What happens when translation fails?
Can a late result overwrite a newer message?
Does the reader still have access to the author's words?
Are images, files, or other unsupported content offered a control that cannot work?
Can users report the source message rather than an altered rendering?

The durable engineering skill here is not producing another chat screen. It is preserving authorship and user control while asynchronous features succeed, fail, and race.

In this tutorial, we will build the application-side state for a multilingual portfolio and project-critique community using Tencent RTC Social Messaging and TUIChat's on-demand message translation. Tencent RTC's Social Messaging solution covers scenarios including group discussions, large communities, rich media, and interest-based social experiences: Social Messaging solution.

The translation-specific implementation reference is TUIChat message translation. That documentation defines the supported content types, languages, and applicable edition limits. Check those current constraints for your target platform instead of hard-coding assumptions from this article.

The user contract comes before the translation call

Consider a community member reviewing a developer's project:

The author posts a text description in a group.
A reader chooses Translate and a target language.
The UI shows progress without hiding the source.
The translated text appears as a secondary view.
The reader can reveal the original, retry a failure, or report the source message.
If the message changes while translation is running, the old result is discarded.

The central invariant is:

A translation is a reader-specific rendering of a message, never a replacement for the canonical message.

That gives us a practical state model:

State	Visible behavior	Allowed next actions
`idle`	Original message and Translate control	Request translation
`loading`	Original remains visible; progress is announced	Wait or change target language
`ready`	Original plus labeled translation	Show original, change language
`failed`	Original plus a non-destructive error	Retry or continue with original
`unsupported`	Original plus an explanation	No retry until content or capability changes

Notice what is absent: there is no state in which the original disappears.

Create the reproducible TypeScript project

The coordinator below is SDK-independent, so we can test races without a network connection or production community.

mkdir community-translation-state
cd community-translation-state
npm init -y
npm install --save-dev typescript vitest @types/node
npm pkg set scripts.test="vitest run"
mkdir src

Add src/translation.ts:

export type CommunityMessage = {
  id: string;
  revision: number;
  authorId: string;
  kind: "text" | "image" | "file" | "custom";
  text?: string;
};

export type TranslationView =
  | { status: "idle" }
  | { status: "loading"; requestId: number }
  | { status: "ready"; translatedText: string }
  | { status: "failed"; reason: FailureReason }
  | { status: "unsupported"; reason: string };

export type FailureReason =
  | "temporarily-unavailable"
  | "invalid-response"
  | "not-entitled";

export type TranslationInput = {
  messageId: string;
  sourceRevision: number;
  sourceText: string;
  targetLanguage: string;
};

// This is an application-owned port, not a Tencent RTC API name.
export interface TranslationGateway {
  translate(input: TranslationInput): Promise<{ text: string }>;
}

export type TranslationPolicy = {
  enabled: boolean;
  supportedTargets: ReadonlySet<string>;
};

function cacheKey(message: CommunityMessage, target: string): string {
  return `${message.id}:${message.revision}:${target}`;
}

export class TranslationCoordinator {
  private readonly entries = new Map<string, TranslationView>();
  private readonly latestRevision = new Map<string, number>();
  private nextRequestId = 1;

  constructor(
    private readonly gateway: TranslationGateway,
    private readonly policy: TranslationPolicy
  ) {}

  sourceChanged(messageId: string, revision: number): void {
    this.latestRevision.set(messageId, revision);
  }

  view(message: CommunityMessage, target: string): TranslationView {
    return this.entries.get(cacheKey(message, target)) ?? { status: "idle" };
  }

  async request(message: CommunityMessage, target: string): Promise<void> {
    this.sourceChanged(message.id, message.revision);
    const key = cacheKey(message, target);

    if (message.kind !== "text" || !message.text?.trim()) {
      this.entries.set(key, {
        status: "unsupported",
        reason: "Only an eligible text message can be translated."
      });
      return;
    }

    if (!this.policy.enabled) {
      this.entries.set(key, {
        status: "unsupported",
        reason: "Translation is not enabled for this deployment."
      });
      return;
    }

    if (!this.policy.supportedTargets.has(target)) {
      this.entries.set(key, {
        status: "unsupported",
        reason: "That target language is not enabled."
      });
      return;
    }

    const existing = this.entries.get(key);
    if (existing?.status === "loading" || existing?.status === "ready") {
      return;
    }

    const requestId = this.nextRequestId++;
    this.entries.set(key, { status: "loading", requestId });

    try {
      const result = await this.gateway.translate({
        messageId: message.id,
        sourceRevision: message.revision,
        sourceText: message.text,
        targetLanguage: target
      });

      const current = this.entries.get(key);
      const revisionIsCurrent =
        this.latestRevision.get(message.id) === message.revision;

      if (
        current?.status !== "loading" ||
        current.requestId !== requestId ||
        !revisionIsCurrent
      ) {
        return;
      }

      if (!result.text.trim()) {
        this.entries.set(key, {
          status: "failed",
          reason: "invalid-response"
        });
        return;
      }

      this.entries.set(key, {
        status: "ready",
        translatedText: result.text
      });
    } catch (error) {
      const current = this.entries.get(key);
      if (
        current?.status !== "loading" ||
        current.requestId !== requestId
      ) {
        return;
      }

      this.entries.set(key, {
        status: "failed",
        reason:
          error instanceof TranslationEntitlementError
            ? "not-entitled"
            : "temporarily-unavailable"
      });
    }
  }
}

export class TranslationEntitlementError extends Error {}

The coordinator deliberately stores translations by message ID, source revision, and target language. A result for revision 3 cannot be presented as the translation of revision 4.

It also deduplicates requests that are already loading or ready. This prevents repeated button presses from creating parallel work for the same view.

Prove the dangerous paths first

Create src/translation.test.ts:

import { describe, expect, it } from "vitest";
import {
  TranslationCoordinator,
  type TranslationGateway
} from "./translation";

const policy = {
  enabled: true,
  // Test identifiers only. Configure production values from the official docs.
  supportedTargets: new Set(["target-a"])
};

const textMessage = {
  id: "message-42",
  revision: 1,
  authorId: "author-7",
  kind: "text" as const,
  text: "Please review the keyboard navigation in my project."
};

describe("TranslationCoordinator", () => {
  it("keeps a successful translation scoped to its source revision", async () => {
    let finish!: (value: { text: string }) => void;

    const gateway: TranslationGateway = {
      translate: () => new Promise(resolve => {
        finish = resolve;
      })
    };

    const coordinator = new TranslationCoordinator(gateway, policy);
    const pending = coordinator.request(textMessage, "target-a");

    const edited = {
      ...textMessage,
      revision: 2,
      text: "Please review keyboard and screen-reader navigation."
    };

    coordinator.sourceChanged(edited.id, edited.revision);
    finish({ text: "late translation of revision one" });
    await pending;

    expect(coordinator.view(edited, "target-a")).toEqual({
      status: "idle"
    });
  });

  it("marks non-text content unsupported without calling the gateway", async () => {
    let calls = 0;
    const gateway: TranslationGateway = {
      async translate() {
        calls += 1;
        return { text: "unexpected" };
      }
    };

    const coordinator = new TranslationCoordinator(gateway, policy);
    const image = {
      ...textMessage,
      kind: "image" as const,
      text: undefined
    };

    await coordinator.request(image, "target-a");

    expect(calls).toBe(0);
    expect(coordinator.view(image, "target-a").status).toBe("unsupported");
  });

  it("exposes a retryable failure instead of removing the original", async () => {
    const gateway: TranslationGateway = {
      async translate() {
        throw new Error("network unavailable");
      }
    };

    const coordinator = new TranslationCoordinator(gateway, policy);
    await coordinator.request(textMessage, "target-a");

    expect(coordinator.view(textMessage, "target-a")).toEqual({
      status: "failed",
      reason: "temporarily-unavailable"
    });

    // The source is owned by the message view, not the translation state.
    expect(textMessage.text).toContain("keyboard navigation");
  });

  it("does not request a target language outside deployment policy", async () => {
    let calls = 0;
    const gateway: TranslationGateway = {
      async translate() {
        calls += 1;
        return { text: "unexpected" };
      }
    };

    const coordinator = new TranslationCoordinator(gateway, policy);
    await coordinator.request(textMessage, "unconfigured-target");

    expect(calls).toBe(0);
    expect(
      coordinator.view(textMessage, "unconfigured-target").status
    ).toBe("unsupported");
  });
});

Run the suite:

npm test

These tests verify application behavior, not translation quality. Language quality needs a separate review process involving fluent speakers and community-specific vocabulary.

Connect the state to TUIChat

There are two reasonable integration paths.

Path A: Use TUIChat's provided translation experience

Choose this when its supported UI and behavior fit your product. Follow the platform-specific setup in the official TUIChat message translation documentation, including its current content-type, language, and edition requirements.

You should still apply the product rules from this tutorial around the component:

retain the canonical source message;
keep reporting and moderation actions attached to the source message ID;
avoid presenting translation as the author's exact wording;
disable or omit controls for unsupported content;
test behavior when the capability is unavailable.

Path B: Put a custom community UI around the capability

Choose this when your project showcase needs its own message cards, critique workflow, accessibility treatment, or translation cache policy.

Implement TranslationGateway in the platform integration layer. The exact Tencent RTC call and callback shape must come from the current documentation for your target platform; the interface below is intentionally application-owned rather than a claimed SDK API:

class TUIChatTranslationGateway implements TranslationGateway {
  async translate(input: TranslationInput): Promise<{ text: string }> {
    // 1. Invoke the documented TUIChat translation integration.
    // 2. Correlate the response with input.messageId and input.sourceRevision.
    // 3. Convert the documented result into { text }.
    // 4. Convert entitlement/configuration failures into
    //    TranslationEntitlementError.
    throw new Error("Wire this adapter using the official platform guide");
  }
}

Keeping this adapter narrow is useful. Tencent RTC integration details remain at the boundary, while stale-result rejection, retries, and UI state stay deterministic and locally testable.

Do not populate supportedTargets from guesses. Build deployment configuration from the currently documented language list and the capability enabled for your Tencent RTC setup. If that configuration cannot be verified, hide the control rather than offering a button that predictably fails.

Render translations as annotations, not replacements

A message card should continue rendering message.text in every translation state. The translation block is additive:

<article aria-labelledby={`author-${message.id}`}>
  <header id={`author-${message.id}`}>{authorDisplayName}</header>

  <p lang={sourceLanguage}>{message.text}</p>

  {state.status === "loading" && (
    <p role="status">Translating… The original remains available.</p>
  )}

  {state.status === "ready" && (
    <section aria-label="Translation">
      <p className="translation-label">Translated text</p>
      <p lang={targetLanguage}>{state.translatedText}</p>
    </section>
  )}

  {state.status === "failed" && (
    <div role="status">
      Translation is unavailable. You can retry or read the original.
      <button onClick={retry}>Retry translation</button>
    </div>
  )}

  {state.status === "idle" && (
    <button
      onClick={requestTranslation}
      aria-label={`Translate message from ${authorDisplayName}`}
    >
      Translate
    </button>
  )}
</article>

For bidirectional text, derive direction from reviewed locale metadata and set dir on the relevant source and translation containers. Do not infer direction from the characters in a single message.

Also avoid announcing an entire translated paragraph through a live region. Announce the status change, then let the reader navigate to the translation normally. Otherwise a long critique may interrupt a screen-reader user's current task.

Failure behavior is part of the community design

A message is edited while translation is loading

Advance the application's message revision and call sourceChanged. The late translation is ignored. Offer translation again for the new revision.

If your messaging layer does not expose revisions, maintain an application-side content version when processing message events. A content hash is another option, but do not use raw message text in logs or analytics merely to support correlation.

A message is deleted while translation is loading

Remove the message card and invalidate its local state. A late result must not recreate deleted content. Server-side deletion and retention policy remain authoritative.

Translation is unavailable for the deployment

Treat this as a capability/configuration state, not an endless network retry. Hide or disable the control with a useful explanation for operators. Confirm current edition limits in the official documentation rather than assuming every deployment has the same feature set.

The content type cannot be translated

Do not send image captions, file metadata, or custom message payloads through a text path unless the official capability explicitly supports that content and your privacy policy permits it. An absent control is clearer than a failing one.

The result is fluent but misleading

A successful API response is not proof of semantic accuracy. Keep the original one action away, label the translation, and provide a correction or reporting path suitable for your community.

For moderation, retain the source message ID, author ID, and source content under your normal access controls. A moderator may need both source and translated views, but the translated rendering should not silently become evidence of what the author literally wrote.

The reader changes target language rapidly

Use a separate cache key per target language and render only the currently selected key. Consider limiting concurrent requests in the UI, but do not erase a previously successful translation merely because another target failed.

When to use built-in UI and when to own more state

Use the provided TUIChat experience when:

its supported message types and languages match the community;
the standard interaction fits the product;
minimizing custom maintenance is more important than bespoke presentation.

Add an application coordinator when:

messages can be edited while asynchronous work is pending;
your UI supports several target-language views;
accessibility requirements need custom announcements or layout;
you need explicit retry, telemetry, or cache policy;
project critique, reporting, or moderation must remain tied to canonical content.

The trade-off is straightforward: custom state gives you clearer product guarantees, but your team becomes responsible for lifecycle testing and accessible rendering. It does not make the translation engine more accurate.

Verification checklist

Before enabling translation in a community, verify all of the following:

[ ] The deployment's supported content types, languages, and edition requirements were checked against the current official documentation.
[ ] Translation is initiated by a visible user action rather than silently replacing every message.
[ ] The source message remains available during loading, success, and failure.
[ ] A result from an old message revision cannot appear under a newer revision.
[ ] Deleted messages cannot reappear through late translation callbacks.
[ ] Duplicate clicks do not create duplicate requests for the same revision and target.
[ ] Unsupported content does not reach the translation integration.
[ ] Empty or malformed results are treated as failures.
[ ] Reporting and moderation retain the canonical message ID.
[ ] Source and target language containers have reviewed lang and dir metadata.
[ ] Loading and failure state changes are accessible without announcing entire messages unexpectedly.
[ ] Logs contain IDs, state transitions, and error categories—not private message bodies.
[ ] Fluent speakers have reviewed representative community vocabulary and failure copy.

A multilingual feature does not need to pretend that language differences have disappeared. It needs to make participation easier without blurring who said what. That is the difference between a convincing showcase and community infrastructure people can actually trust.

Discussion

If you were adding translation to a developer community, would you cache successful translations per message revision, or always request a fresh rendering? What retention and correction rules would make that decision acceptable for your users?

Relationship disclosure: I prepared this article in connection with Tencent RTC developer content. Official Tencent RTC Social Messaging and TUIChat documentation was used as the implementation reference.

Don’t Stack Every Beauty AR Effect: Build a Runtime Budget Arbiter for GAN, Segmentation, and Avatars

LunarDrift — Fri, 02 Oct 2026 17:11:08 +0000

A shared demo has a predictable failure mode: every contributor adds something visually impressive, and nobody wants to remove anything.

A beauty filter is joined by background segmentation. Then someone adds a GAN effect, a 3D avatar, and a sticker layer. The pull requests all work independently. The combined application does not.

The tension is not that the team lacks AI features. It is that saying “no” to an effect can feel less ambitious than stacking everything—especially during a hackathon or community build. But a reliable Beauty AR experience needs an explicit rendering budget, not optimism.

In this tutorial, we will build an application-level runtime budget arbiter that:

allows only one intensive presentation mode at a time;
distinguishes the user’s requested mode from the mode currently visible;
blocks unsupported GAN, segmentation, or 3D modes on constrained devices;
applies a basic fallback only when the user has approved it;
removes an intensive mode if the device is reclassified during the session;
restores the last working mode after an application failure; and
exposes every decision as testable state.

Tencent RTC’s Beauty AR overview describes capabilities including real-time beauty filters, makeup, stickers, virtual backgrounds, avatars, gesture recognition, and image or video enhancement. Its Low-End Device Performance Optimization Practice Guide recommends adapting effects to device tiers, including disabling expensive segmentation or 3D/GAN effects and controlling resolution and frame rate.

The controller below turns that guidance into deterministic application behavior without inventing a universal device benchmark.

Start with the collision, not the SDK call

Consider these user actions:

1. User selects a segmented background.
2. The background becomes visible.
3. User selects a GAN portrait mode.
4. The application removes segmentation before enabling GAN.
5. Device pressure becomes sustained.
6. The device is reclassified as constrained.
7. GAN is removed.
8. Basic enhancement is enabled only if the user approved that fallback.

There are three different facts in this sequence:

Requested mode: what the user most recently chose.
Desired mode: what policy currently permits.
Visible mode: what the renderer last applied successfully.

Collapsing those into one currentEffect variable creates misleading UI. For example, the application may say “GAN selected” while the asset is still loading or while policy has already rejected it.

We will keep those facts separate.

The admission policy

This tutorial uses five application-owned modes:

Mode	Classification	Constrained device	Standard device
`off`	No Beauty AR presentation	Allow	Allow
`basic`	Basic enhancement profile	Allow	Allow
`ganPortrait`	Intensive	Block or consented fallback	Allow
`segmentedBackground`	Intensive	Block or consented fallback	Allow
`avatar3d`	Intensive	Block or consented fallback	Allow

These are product-policy names, not Tencent RTC API names. Your adapter will map them to the supported SDK operations for your target platform.

The important rule is that a mode represents an exact presentation, rather than another layer to append. Selecting ganPortrait replaces segmentedBackground; it does not silently stack with it.

This policy deliberately leaves stickers and makeup combinations out of the first version. Add combinations only after measuring them on your supported devices. “The SDK can express it” and “our session can afford it” are different statements.

Create the TypeScript project

mkdir beauty-budget-arbiter
cd beauty-budget-arbiter
npm init -y
npm install -D typescript vitest @types/node
mkdir src

Replace package.json with:

{
  "name": "beauty-budget-arbiter",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "typescript": "latest",
    "vitest": "latest"
  }
}

Add tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "outDir": "dist"
  },
  "include": ["src"]
}

Implement the arbiter

Create src/arbiter.ts:

export type BeautyMode =
  | "off"
  | "basic"
  | "ganPortrait"
  | "segmentedBackground"
  | "avatar3d";

export type DeviceCapability = "constrained" | "standard";
export type Phase = "active" | "applying" | "blocked" | "failed";

export interface Selection {
  mode: BeautyMode;

  // This is separate consent. Selecting GAN does not automatically mean
  // that the user accepts a different appearance when GAN is unavailable.
  allowBasicFallback: boolean;
}

export interface BeautyPort {
  /**
   * Apply exactly this mode, removing any mutually exclusive previous mode.
   * Reject if the operation cannot be completed.
   */
  applyMode(mode: BeautyMode): Promise<void>;
}

export interface ArbiterSnapshot {
  capability: DeviceCapability;
  requested: BeautyMode;
  desired: BeautyMode;
  visible: BeautyMode;
  phase: Phase;
  notice: string | null;
}

type Admission =
  | { kind: "admitted"; target: BeautyMode; notice: string | null }
  | { kind: "blocked"; notice: string };

export function isIntensive(mode: BeautyMode): boolean {
  return (
    mode === "ganPortrait" ||
    mode === "segmentedBackground" ||
    mode === "avatar3d"
  );
}

export function admit(
  selection: Selection,
  capability: DeviceCapability,
): Admission {
  if (capability === "standard" || !isIntensive(selection.mode)) {
    return { kind: "admitted", target: selection.mode, notice: null };
  }

  if (selection.allowBasicFallback) {
    return {
      kind: "admitted",
      target: "basic",
      notice: `${selection.mode} is unavailable in the current device profile; basic mode was selected.`,
    };
  }

  return {
    kind: "blocked",
    notice: `${selection.mode} is unavailable in the current device profile and no fallback was approved.`,
  };
}

export class BeautyBudgetArbiter {
  private requested: BeautyMode = "off";
  private desired: BeautyMode = "off";
  private visible: BeautyMode = "off";
  private phase: Phase = "active";
  private notice: string | null = null;
  private lastSelection: Selection = {
    mode: "off",
    allowBasicFallback: false,
  };

  // All renderer mutations are serialized through this queue.
  private tail: Promise<void> = Promise.resolve();

  constructor(
    private capability: DeviceCapability,
    private readonly port: BeautyPort,
  ) {}

  select(selection: Selection): void {
    this.lastSelection = selection;
    this.requested = selection.mode;

    const decision = admit(selection, this.capability);

    if (decision.kind === "blocked") {
      // If an intensive mode is already visible and has become invalid,
      // remove it. Otherwise preserve the last permitted presentation.
      this.desired = isIntensive(this.visible) ? "off" : this.visible;
      this.phase = "blocked";
      this.notice = decision.notice;
    } else {
      this.desired = decision.target;
      this.phase = this.desired === this.visible ? "active" : "applying";
      this.notice = decision.notice;
    }

    this.scheduleReconcile();
  }

  updateCapability(capability: DeviceCapability): void {
    if (capability === this.capability) return;

    this.capability = capability;

    // Re-evaluate the user's last explicit selection. Do not invent a new
    // preference merely because the device classification changed.
    this.select(this.lastSelection);
  }

  snapshot(): ArbiterSnapshot {
    return {
      capability: this.capability,
      requested: this.requested,
      desired: this.desired,
      visible: this.visible,
      phase: this.phase,
      notice: this.notice,
    };
  }

  async whenSettled(): Promise<void> {
    await this.tail;
  }

  private scheduleReconcile(): void {
    this.tail = this.tail.then(() => this.reconcile());
  }

  private async reconcile(): Promise<void> {
    const target = this.desired;

    if (target === this.visible) return;

    const previous = this.visible;

    try {
      await this.port.applyMode(target);
      this.visible = target;

      // A newer selection may have arrived while the port was awaiting.
      this.phase = this.desired === target ? "active" : "applying";
    } catch (error) {
      try {
        // applyMode is an exact-mode contract, so reapplying the previous
        // mode also compensates for a partially completed mutation.
        await this.port.applyMode(previous);
        this.visible = previous;
      } catch {
        // If restoration also fails, prefer an explicit neutral state.
        try {
          await this.port.applyMode("off");
        } finally {
          this.visible = "off";
        }
      }

      this.phase = "failed";
      this.notice = `Could not apply ${target}; restored ${this.visible}.`;
    }
  }
}

There are two intentional constraints here.

First, renderer mutations are serialized. Rapid clicks cannot launch three competing effect changes and let the slowest callback win.

Second, applyMode() means “make this the exact active mode.” The application does not ask the SDK adapter to “add GAN” without accounting for segmentation already being active.

Reproduce the unsafe paths in tests

Create src/arbiter.test.ts:

import { describe, expect, it } from "vitest";
import {
  BeautyBudgetArbiter,
  type BeautyMode,
  type BeautyPort,
} from "./arbiter.js";

class FakeBeautyPort implements BeautyPort {
  history: BeautyMode[] = [];
  failures = new Set<BeautyMode>();

  async applyMode(mode: BeautyMode): Promise<void> {
    this.history.push(mode);

    if (this.failures.has(mode)) {
      throw new Error(`Failed to apply ${mode}`);
    }
  }
}

describe("BeautyBudgetArbiter", () => {
  it("blocks GAN on a constrained device without inventing consent", async () => {
    const port = new FakeBeautyPort();
    const arbiter = new BeautyBudgetArbiter("constrained", port);

    arbiter.select({ mode: "ganPortrait", allowBasicFallback: false });
    await arbiter.whenSettled();

    expect(arbiter.snapshot()).toMatchObject({
      requested: "ganPortrait",
      desired: "off",
      visible: "off",
      phase: "blocked",
    });
    expect(port.history).toEqual([]);
  });

  it("uses basic mode only when fallback consent exists", async () => {
    const port = new FakeBeautyPort();
    const arbiter = new BeautyBudgetArbiter("constrained", port);

    arbiter.select({ mode: "ganPortrait", allowBasicFallback: true });
    await arbiter.whenSettled();

    expect(arbiter.snapshot()).toMatchObject({
      requested: "ganPortrait",
      desired: "basic",
      visible: "basic",
      phase: "active",
    });
    expect(port.history).toEqual(["basic"]);
  });

  it("ends in the latest mode after rapid selections", async () => {
    const port = new FakeBeautyPort();
    const arbiter = new BeautyBudgetArbiter("standard", port);

    arbiter.select({ mode: "segmentedBackground", allowBasicFallback: false });
    arbiter.select({ mode: "ganPortrait", allowBasicFallback: false });
    arbiter.select({ mode: "off", allowBasicFallback: false });

    await arbiter.whenSettled();

    expect(arbiter.snapshot().visible).toBe("off");
    expect(port.history).not.toContain("ganPortrait");
  });

  it("removes an intensive mode after a capability downgrade", async () => {
    const port = new FakeBeautyPort();
    const arbiter = new BeautyBudgetArbiter("standard", port);

    arbiter.select({ mode: "avatar3d", allowBasicFallback: false });
    await arbiter.whenSettled();
    expect(arbiter.snapshot().visible).toBe("avatar3d");

    arbiter.updateCapability("constrained");
    await arbiter.whenSettled();

    expect(arbiter.snapshot()).toMatchObject({
      requested: "avatar3d",
      visible: "off",
      phase: "blocked",
    });
  });

  it("restores the last working mode when the new mode fails", async () => {
    const port = new FakeBeautyPort();
    const arbiter = new BeautyBudgetArbiter("standard", port);

    arbiter.select({ mode: "basic", allowBasicFallback: false });
    await arbiter.whenSettled();

    port.failures.add("ganPortrait");
    arbiter.select({ mode: "ganPortrait", allowBasicFallback: false });
    await arbiter.whenSettled();

    expect(arbiter.snapshot()).toMatchObject({
      requested: "ganPortrait",
      visible: "basic",
      phase: "failed",
    });
    expect(port.history).toEqual(["basic", "ganPortrait", "basic"]);
  });
});

Run the suite:

npm test

These tests verify policy and ordering without requiring a camera. They do not prove that a real device can sustain a selected mode. That remains an on-device verification task.

Connect the port to Tencent RTC Beauty AR

Keep SDK-specific operations outside the arbiter. One useful adapter shape is:

import type { BeautyMode, BeautyPort } from "./arbiter.js";

type BeautyBindings = {
  disableCurrentPresentation(): Promise<void>;
  enableBasic(): Promise<void>;
  enableGanPortrait(): Promise<void>;
  enableSegmentedBackground(): Promise<void>;
  enableAvatar3d(): Promise<void>;
};

export class TencentBeautyAdapter implements BeautyPort {
  constructor(private readonly bindings: BeautyBindings) {}

  async applyMode(mode: BeautyMode): Promise<void> {
    await this.bindings.disableCurrentPresentation();

    switch (mode) {
      case "off":
        return;
      case "basic":
        return this.bindings.enableBasic();
      case "ganPortrait":
        return this.bindings.enableGanPortrait();
      case "segmentedBackground":
        return this.bindings.enableSegmentedBackground();
      case "avatar3d":
        return this.bindings.enableAvatar3d();
    }
  }
}

The binding names above are your own interface, not claims about Tencent RTC API names. Implement them using the official Beauty AR integration documentation for the platform and SDK version you selected.

Disabling the previous presentation before enabling the next one has a trade-off: users may briefly see a neutral transition. The alternative—enabling the candidate first—may temporarily overlap two intensive workloads. Choose deliberately, then verify the transition on real devices.

If your selected SDK integration offers a safe staging mechanism, the adapter can use it without changing the policy controller.

Where the device classification comes from

Do not turn a phone model list into permanent truth. Firmware, thermal conditions, camera resolution, concurrent applications, and the rest of the live session can all affect available budget.

Use two inputs:

A conservative initial classification based on the devices and configurations your team actually supports.
Session measurements from the complete camera, Beauty AR, and RTC workload.

Your capability estimator can call:

arbiter.updateCapability("constrained");

when degradation is sustained, and later return to standard after a separate recovery condition.

Use hysteresis: entering and leaving constrained mode should not depend on the same single threshold or one bad frame. Otherwise, the application can oscillate between GAN and basic modes. This tutorial intentionally does not prescribe universal frame-rate, temperature, or timing thresholds; establish them from repeatable tests on your workload.

Resolution and frame rate are another part of the budget. The official low-end optimization guide recommends controlling them, but reducing them should be represented as an explicit media policy—not hidden inside an effect callback.

Failure modes to drill on hardware

The GAN asset cannot load

Expected behavior:

phase becomes failed;
the previous working mode is restored;
the UI does not claim GAN is visible;
retry is a user-visible action rather than an infinite background loop.

Test with unavailable or invalid test assets in a non-production environment where your integration permits it.

Disabling segmentation succeeds, but enabling the next mode fails

This is why the adapter receives an exact-mode command and the controller reapplies the previous mode. Verify that restoration really reconstructs the previous presentation; do not assume an SDK rejection is atomic.

The user revokes fallback consent

Update the stored selection and run it through the arbiter again. Do not leave basic active merely because it was once approved.

Consent belongs in application state that can be changed and audited—not only in the label of a button shown at first launch.

The application enters the background during an effect change

Decide whether your platform integration pauses, clears, or reconstructs Beauty AR state. On return, compare renderer reality with desired; do not assume the pre-background callback still represents the current session.

Remote configuration changes the policy

Treat remote configuration as an input to admission, not as permission to alter someone’s appearance silently. A remotely disabled GAN mode can become blocked, but switching to basic enhancement still requires the fallback choice already modeled here.

Capability classification flaps

If the application alternates between standard and constrained, fix the estimator. Adding debounce logic to the renderer adapter merely hides an unstable policy signal.

What AI contributes—and what remains a human decision

GAN-based effects and real-time computer vision can produce visual transformations. That is a demonstrated capability, not evidence that an “AI agent” should decide how a person appears.

The human decisions remain:

whether any appearance-changing mode is enabled;
whether a different fallback appearance is acceptable;
whether reduced resolution is an acceptable trade-off;
whether an effect should be removed when the device is under pressure; and
which devices and session conditions the team is willing to support.

The durable engineering skill here is not finding the most impressive model. It is turning visual capability into a bounded system with visible state, consent, measurements, and recovery.

Release verification checklist

Before shipping, verify the complete experience rather than only the TypeScript tests:

[ ] Selecting each mode updates requested immediately.
[ ] The UI shows an applying state until the renderer confirms success.
[ ] Only one intensive mode is visible at a time.
[ ] A constrained classification blocks GAN, segmentation, and 3D modes according to policy.
[ ] Basic fallback is never applied without separate consent.
[ ] A mid-session capability downgrade removes an intensive mode.
[ ] A failed activation restores the previous working presentation.
[ ] A failed restoration reaches an explicit neutral state.
[ ] Rapid selections end in the latest requested and admitted mode.
[ ] Background and foreground transitions reconcile renderer state.
[ ] Tests use the full RTC, camera, and Beauty AR workload at the chosen resolution and frame rate.
[ ] UI language distinguishes requested, unavailable, applying, active, and failed states.

Discussion: should the policy allow combinations?

Eventually, perhaps—but “allow combinations” should mean a measured compatibility table, not an unbounded array of effects.

A sensible next iteration is to identify profiles such as basic + sticker or makeup + segmented background, qualify each complete profile, and continue applying one exact profile at a time. This preserves deterministic rollback and prevents independently contributed features from accidentally creating an unsupported workload.

The arbiter is therefore not a ceiling on creativity. It is the place where the team records which combinations it can responsibly operate.

Disclosure: I have a relationship with Tencent RTC, and I used the official Tencent RTC documentation as the implementation reference for this article.

Stop Sending Half-Sentences to OpenAI in a Tencent RTC Voice Companion

LunarDrift — Sat, 26 Sep 2026 17:11:27 +0000

Voice-companion demos invite an obvious question: Which model makes the smartest or most charming character?

That is rarely the first production decision. A capable model still feels broken if your application sends it half a sentence, repeats a finalized transcript, or plays a response after the user has already started a new turn.

The practical tension is between responsiveness and certainty:

Commit too early and OpenAI receives incomplete thoughts.
Wait too long and the companion feels unresponsive.
Retry carelessly and the character answers twice.

This tutorial builds a small Python utterance commit gate for a Tencent RTC Conversational AI application. It waits for a configurable quiet window, correlates every downstream operation, and makes recovery explicit. The result is not a smarter model. It is a voice pipeline that gives the model coherent turns.

What we are building

Keep the media and AI responsibilities separate:

Microphone
   │
   ▼
Tencent RTC media transport
   │
   ▼
Speech recognition ── partial/final segments
   │
   ▼
Utterance commit gate  ← this tutorial
   │
   ├── LLM request
   ├── output moderation
   └── speech synthesis
            │
            ▼
      RTC audio playback

Tencent RTC's Conversational AI scenario supports real-time voice interaction with multiple LLM providers. Its LLM configuration documentation also describes connecting OpenAI-compatible models and carrying request identifiers for routing and observability:

The Python types below are deliberately application-owned. They are not Tencent RTC SDK API names. Your adapter translates actual speech, model, moderation, synthesis, and RTC callbacks into these events.

The state contract

Our controller recognizes six states:

State	Meaning	Permitted next step
`LISTENING`	Collecting partial or final transcript segments	Wait or begin settling
`SETTLING`	All known segments are final; quiet timer is running	Commit or accept another segment
`THINKING`	One LLM request owns the turn	Moderate its result or cancel it
`MODERATING`	The generated draft is being checked	Speak it or enter recovery
`SPEAKING`	Approved audio is being presented	Finish or be interrupted
`RECOVERING`	The current operation has an uncertain or failed outcome	Resume explicitly

Three invariants matter more than the exact state names:

There is at most one active request identifier.
A callback is accepted only if it matches the active request and state.
Reconnection creates a new session epoch, so old transcript callbacks cannot become new turns.

Create the project

This example uses only the Python standard library and Python 3.11 or newer.

mkdir rtc-turn-commit
cd rtc-turn-commit
touch companion.py test_companion.py

Add the controller to companion.py:

from __future__ import annotations

from dataclasses import dataclass
from enum import Enum, auto
from typing import Optional


class Mode(Enum):
    LISTENING = auto()
    SETTLING = auto()
    THINKING = auto()
    MODERATING = auto()
    SPEAKING = auto()
    RECOVERING = auto()
    STOPPED = auto()


@dataclass(frozen=True)
class Transcript:
    epoch: int
    segment_id: str
    revision: int
    text: str
    final: bool


@dataclass
class StoredSegment:
    revision: int
    text: str
    final: bool
    order: int


@dataclass(frozen=True)
class Effect:
    kind: str
    request_id: Optional[str] = None
    text: Optional[str] = None


class TurnCommitter:
    def __init__(
        self,
        settle_ms: int = 350,
        transcript_timeout_ms: int = 8_000,
    ) -> None:
        if settle_ms < 0:
            raise ValueError("settle_ms must be non-negative")
        if transcript_timeout_ms <= settle_ms:
            raise ValueError("transcript timeout must exceed settle time")

        self.settle_ms = settle_ms
        self.transcript_timeout_ms = transcript_timeout_ms
        self.mode = Mode.LISTENING
        self.epoch = 1

        self._segments: dict[str, StoredSegment] = {}
        self._consumed_segment_ids: set[str] = set()
        self._next_order = 0
        self._first_segment_at: Optional[int] = None
        self._settle_deadline: Optional[int] = None

        self._turn_number = 0
        self._active_request: Optional[str] = None

    @property
    def active_request(self) -> Optional[str]:
        return self._active_request

    def on_transcript(self, event: Transcript, now_ms: int) -> list[Effect]:
        if self.mode not in (Mode.LISTENING, Mode.SETTLING):
            return []
        if event.epoch != self.epoch:
            return []
        if event.segment_id in self._consumed_segment_ids:
            return []

        previous = self._segments.get(event.segment_id)
        if previous and event.revision <= previous.revision:
            return []

        if previous is None:
            order = self._next_order
            self._next_order += 1
        else:
            order = previous.order

        self._segments[event.segment_id] = StoredSegment(
            revision=event.revision,
            text=event.text.strip(),
            final=event.final,
            order=order,
        )

        if self._first_segment_at is None:
            self._first_segment_at = now_ms

        if self._segments and all(s.final for s in self._segments.values()):
            self.mode = Mode.SETTLING
            self._settle_deadline = now_ms + self.settle_ms
        else:
            self.mode = Mode.LISTENING
            self._settle_deadline = None

        return []

    def tick(self, now_ms: int) -> list[Effect]:
        if (
            self._first_segment_at is not None
            and now_ms - self._first_segment_at >= self.transcript_timeout_ms
            and self.mode in (Mode.LISTENING, Mode.SETTLING)
        ):
            self._clear_transcript()
            self.mode = Mode.RECOVERING
            return [Effect("status", text="transcript_timeout")]

        if (
            self.mode != Mode.SETTLING
            or self._settle_deadline is None
            or now_ms < self._settle_deadline
        ):
            return []

        ordered = sorted(self._segments.items(), key=lambda item: item[1].order)
        text = " ".join(segment.text for _, segment in ordered if segment.text)
        text = " ".join(text.split())

        for segment_id, _ in ordered:
            self._consumed_segment_ids.add(segment_id)
        self._clear_transcript()

        if not text:
            self.mode = Mode.LISTENING
            return []

        self._turn_number += 1
        request_id = f"session-{self.epoch}-turn-{self._turn_number}"
        self._active_request = request_id
        self.mode = Mode.THINKING

        return [Effect("generate", request_id=request_id, text=text)]

    def on_llm_result(self, request_id: str, draft: str) -> list[Effect]:
        if self.mode != Mode.THINKING or request_id != self._active_request:
            return []

        self.mode = Mode.MODERATING
        return [Effect("moderate", request_id=request_id, text=draft)]

    def on_moderation_result(
        self,
        request_id: str,
        allowed: bool,
        approved_text: str = "",
    ) -> list[Effect]:
        if self.mode != Mode.MODERATING or request_id != self._active_request:
            return []

        if not allowed:
            self._active_request = None
            self.mode = Mode.RECOVERING
            return [Effect("status", text="reply_blocked")]

        self.mode = Mode.SPEAKING
        return [
            Effect("speak", request_id=request_id, text=approved_text)
        ]

    def on_user_speech_started(self) -> list[Effect]:
        effects: list[Effect] = []

        if self.mode in (Mode.THINKING, Mode.MODERATING):
            effects.append(Effect("cancel_generation", self._active_request))
        elif self.mode == Mode.SPEAKING:
            effects.append(Effect("stop_speech", self._active_request))

        if self.mode in (Mode.THINKING, Mode.MODERATING, Mode.SPEAKING):
            self._active_request = None
            self.mode = Mode.LISTENING

        return effects

    def on_speech_finished(self, request_id: str) -> list[Effect]:
        if self.mode != Mode.SPEAKING or request_id != self._active_request:
            return []

        self._active_request = None
        self.mode = Mode.LISTENING
        return []

    def on_stage_error(self, request_id: str, stage: str) -> list[Effect]:
        if request_id != self._active_request:
            return []

        self._active_request = None
        self.mode = Mode.RECOVERING
        return [Effect("status", text=f"{stage}_failed")]

    def on_disconnect(self) -> list[Effect]:
        effects: list[Effect] = []

        if self.mode in (Mode.THINKING, Mode.MODERATING):
            effects.append(Effect("cancel_generation", self._active_request))
        elif self.mode == Mode.SPEAKING:
            effects.append(Effect("stop_speech", self._active_request))

        self.epoch += 1
        self._active_request = None
        self._consumed_segment_ids.clear()
        self._clear_transcript()
        self.mode = Mode.RECOVERING
        effects.append(Effect("status", text="connection_lost"))
        return effects

    def resume(self) -> None:
        if self.mode == Mode.RECOVERING:
            self.mode = Mode.LISTENING

    def stop(self) -> None:
        self._active_request = None
        self._clear_transcript()
        self.mode = Mode.STOPPED

    def _clear_transcript(self) -> None:
        self._segments.clear()
        self._first_segment_at = None
        self._settle_deadline = None

Reproduce the races before connecting a microphone

Add deterministic tests to test_companion.py:

import unittest

from companion import Effect, Mode, Transcript, TurnCommitter


class TurnCommitterTests(unittest.TestCase):
    def test_two_final_segments_become_one_model_request(self) -> None:
        c = TurnCommitter(settle_ms=300)

        c.on_transcript(
            Transcript(c.epoch, "a", 1, "Could you explain", True),
            now_ms=0,
        )
        self.assertEqual(c.tick(299), [])

        # A second final segment restarts the settling window.
        c.on_transcript(
            Transcript(c.epoch, "b", 1, "Python generators?", True),
            now_ms=250,
        )
        self.assertEqual(c.tick(549), [])

        self.assertEqual(
            c.tick(550),
            [
                Effect(
                    "generate",
                    "session-1-turn-1",
                    "Could you explain Python generators?",
                )
            ],
        )
        self.assertEqual(c.mode, Mode.THINKING)

    def test_duplicate_revision_cannot_create_a_second_turn(self) -> None:
        c = TurnCommitter(settle_ms=100)
        event = Transcript(c.epoch, "segment-1", 2, "Hello", True)

        c.on_transcript(event, now_ms=0)
        first = c.tick(100)
        self.assertEqual(len(first), 1)

        c.on_user_speech_started()
        c.on_transcript(event, now_ms=200)
        self.assertEqual(c.tick(500), [])

    def test_interruption_invalidates_late_model_output(self) -> None:
        c = TurnCommitter(settle_ms=100)
        c.on_transcript(
            Transcript(c.epoch, "a", 1, "Tell me a story", True),
            now_ms=0,
        )
        request = c.tick(100)[0].request_id

        self.assertEqual(
            c.on_user_speech_started(),
            [Effect("cancel_generation", request)],
        )

        # Cancellation is best-effort. The old callback may still arrive.
        self.assertEqual(c.on_llm_result(request, "Once upon a time"), [])
        self.assertEqual(c.mode, Mode.LISTENING)

    def test_reconnect_rejects_old_transcript_callbacks(self) -> None:
        c = TurnCommitter(settle_ms=100)
        old_epoch = c.epoch

        c.on_disconnect()
        c.resume()

        c.on_transcript(
            Transcript(old_epoch, "late", 1, "Old audio", True),
            now_ms=0,
        )
        self.assertEqual(c.tick(500), [])
        self.assertEqual(c.mode, Mode.LISTENING)

    def test_partial_transcript_eventually_enters_recovery(self) -> None:
        c = TurnCommitter(
            settle_ms=100,
            transcript_timeout_ms=1_000,
        )
        c.on_transcript(
            Transcript(c.epoch, "a", 1, "unfinished", False),
            now_ms=0,
        )

        self.assertEqual(
            c.tick(1_000),
            [Effect("status", text="transcript_timeout")],
        )
        self.assertEqual(c.mode, Mode.RECOVERING)


if __name__ == "__main__":
    unittest.main()

Run the suite:

python -m unittest -v

You should see five passing tests. More importantly, the tests prove behavioral properties rather than relying on real-time sleeps:

Two final segments can still represent one utterance.
Duplicate recognition callbacks do not create duplicate model calls.
Best-effort cancellation is backed by stale-result rejection.
Reconnection invalidates callbacks from the previous media session.
A partial transcript cannot leave the application waiting forever.

Connect the effects to your live application

Keep provider-specific code outside the controller. A simplified dispatcher might look like this:

async def apply_effect(effect, services, controller):
    try:
        if effect.kind == "generate":
            draft = await services.llm.generate(
                prompt=effect.text,
                correlation_id=effect.request_id,
            )
            for next_effect in controller.on_llm_result(
                effect.request_id,
                draft,
            ):
                await apply_effect(next_effect, services, controller)

        elif effect.kind == "moderate":
            result = await services.moderation.check(effect.text)
            next_effects = controller.on_moderation_result(
                effect.request_id,
                allowed=result.allowed,
                approved_text=result.approved_text,
            )
            for next_effect in next_effects:
                await apply_effect(next_effect, services, controller)

        elif effect.kind == "speak":
            await services.speech.play(
                text=effect.text,
                correlation_id=effect.request_id,
            )

        elif effect.kind == "cancel_generation":
            await services.llm.cancel(effect.request_id)

        elif effect.kind == "stop_speech":
            await services.speech.stop(effect.request_id)

        elif effect.kind == "status":
            services.ui.show_status(effect.text)

    except Exception:
        # Classify the actual stage in production rather than using
        # one broad exception handler.
        for recovery_effect in controller.on_stage_error(
            effect.request_id,
            effect.kind,
        ):
            services.ui.show_status(recovery_effect.text)

services.llm, services.moderation, and services.speech are ports owned by your application. Map correlation_id to the request-identifier mechanism supported by your configured integration; do not assume the pseudocode argument name is an SDK field.

The live event flow is then:

Join the RTC conversation and start the chosen recognition path.
Forward every transcript revision to on_transcript().
Call tick() from your application timer.
Execute emitted effects through provider adapters.
Call on_user_speech_started() when your turn-detection policy confirms a new user turn.
Call on_speech_finished() only after playback completion is confirmed.
On transport loss, call on_disconnect() before attempting to rejoin.
Call resume() after the media and recognition path is ready again.

The Tencent RTC Social Entertainment solution includes AI virtual companions and character dialogue among its scenarios. The commit gate applies equally to a playful character, an assistant, or an AI host because it controls turns rather than personality.

Choosing the quiet window

Do not copy 350 ms into production and call it solved. It is an initial configuration value, not a universal latency target.

Choose it with a replay set containing your application's actual conversational patterns:

Observation	Likely adjustment	Trade-off
Clause-ending pauses create separate requests	Increase the settling window	Slower response start
Complete commands feel delayed	Decrease the settling window	More premature commits
Recognition emits several final segments per sentence	Keep segment aggregation enabled	Requires stable ordering and IDs
Very long partials never finalize	Review recognition behavior and timeout policy	Recovery may ask the user to repeat

Record at least these timestamps per request identifier:

first_transcript_at
last_final_segment_at
utterance_committed_at
llm_started_at
llm_finished_at
moderation_finished_at
speech_playback_started_at
speech_playback_finished_at

This separates distinct delays. A single “AI latency” number cannot tell you whether time was spent waiting for a turn boundary, generating text, checking the output, synthesizing speech, or starting playback.

Failure behavior users can understand

Recognition never marks the segment final

The transcript timeout enters RECOVERING and emits transcript_timeout. Show a visible and, when possible, accessible prompt such as “I didn't catch the end of that.” Do not submit the partial text as though it were confirmed.

The LLM completes after interruption

Provider cancellation may fail or arrive too late. The request-ID check is the authoritative defense: a callback without current ownership produces no speech.

Moderation is unavailable

Do not silently bypass the stage. Move to recovery, keep the draft out of synthesis, and let the user retry. For a social companion, moderation and user-visible control belong in the runtime design, not only in the prompt.

Speech synthesis fails after text was approved

The generated answer may be valid while its delivery outcome is unknown. Show a failure state and return to listening only through an explicit recovery action. Automatically generating a new answer could duplicate content.

The network reconnects while callbacks are queued

Increment the epoch before rejoining. Old ASR callbacks are then structurally incapable of forming a new request. Start a fresh turn rather than pretending an interrupted utterance continued seamlessly.

The process restarts

This in-memory example intentionally does not resume an in-flight turn. A restarted service should create a new epoch and expose the interruption. If you later persist state, store the epoch, active request identifier, mode, and committed transcript together; restoring only the transcript can replay a turn without restoring its ownership rules.

Verification checklist for staging

Run these drills with real audio and your configured providers:

[ ] Pause between two clauses and confirm only one LLM request is logged.
[ ] Deliver the same final transcript revision twice and confirm one commit.
[ ] Interrupt during generation and confirm late output never reaches synthesis.
[ ] Interrupt during playback and confirm old completion callbacks do not reset the new turn.
[ ] Disconnect after a final segment but before the quiet window expires.
[ ] Reconnect and inject a callback carrying the previous epoch.
[ ] Make moderation time out and confirm the draft is not spoken.
[ ] Make synthesis fail and confirm the UI does not claim the answer was delivered.
[ ] Confirm logs carry one request identifier through LLM, moderation, and synthesis.
[ ] Confirm microphone, transcript, and generated-content handling match your consent and privacy policy.

The useful decision behind the “better AI pet” discussion

A model can demonstrably generate engaging character dialogue. That does not demonstrate that a live companion can identify a completed turn, recover from a partition, or respect an interruption.

The human decision underneath the model comparison is where to spend the next engineering cycle. Before changing models or expanding the character prompt, inspect ten imperfect voice sessions. If you find split sentences, duplicate requests, or stale replies, add a commit gate and correlation logging first. Model evaluation becomes more meaningful once every candidate receives the same coherent input turns.

Disclosure: This article was produced in connection with Tencent RTC. Official Tencent RTC documentation was used as the implementation reference.

Make GAN Effects Fail in CI, Not on Low-End Devices

LunarDrift — Thu, 24 Sep 2026 17:12:13 +0000

A Beauty AR demo can be completely convincing while avoiding the question that matters in production: what happens when this effect reaches a device that should not run it?

That gap is easy to interpret as a skills problem—perhaps you need to learn more rendering internals or test every phone. Usually, the missing skill is narrower and more valuable: expressing rollout decisions as code.

In this tutorial, we will build a small policy gate for a Tencent RTC Beauty AR integration. It will:

classify Beauty AR profiles by relative cost;
keep GAN, segmentation, and 3D effects away from conservative device tiers;
require every expensive profile to have a cheaper fallback;
reject cyclic or incomplete fallback chains in GitHub Actions;
expose runtime states such as applying, degraded, and blocked;
verify the policy without requiring a camera or Beauty AR asset in CI.

The profile fields below belong to our application. They are deliberately not presented as Tencent RTC SDK API names. The final adapter is where each profile must be mapped to the documented integration surface for your target platform.

Why a policy gate belongs in the implementation

Tencent RTC Beauty AR covers real-time beauty filters, makeup, stickers, virtual backgrounds, avatars, gesture recognition, and image or video enhancement. The product overview is here:

https://trtc.io/document/beauty-ar-overview

Those capabilities do not all have the same device cost. Tencent RTC's low-end optimization guide recommends adapting effects by device tier, selecting appropriate performance modes, controlling resolution and frame rate, and disabling expensive capabilities such as segmentation or 3D/GAN effects where necessary:

https://trtc.io/document/66968

The documentation gives us an engineering direction, not a universal tier table. Your application still has to decide:

How a device enters a tier.
Which effects that tier permits.
What replaces an effect when loading or application fails.
Whether a session may upgrade again after degradation.
How configuration changes are reviewed and tested.

We will put decisions 2–5 into reproducible code. Device classification remains an application-specific input because it should be based on measurements from your supported hardware rather than a borrowed benchmark.

The repository we will build

Use Node.js 22 or another version supported by your own toolchain.

beauty-policy-gate/
├── beauty-policy.json
├── runtime.mjs
├── validate-policy.mjs
├── validate-policy.test.mjs
└── .github/
    └── workflows/
        └── beauty-policy.yml

No runtime dependencies are required.

mkdir beauty-policy-gate
cd beauty-policy-gate
npm init -y

Add these scripts to package.json:

{
  "type": "module",
  "scripts": {
    "validate": "node validate-policy.mjs beauty-policy.json",
    "test": "node --test"
  }
}

Describe the rollout as data

Create beauty-policy.json:

{
  "version": 1,
  "entryByTier": {
    "low": "basic",
    "mid": "standard",
    "high": "gan-showcase"
  },
  "tierRules": {
    "low": ["segmentation", "avatar3d", "gan"],
    "mid": ["avatar3d", "gan"],
    "high": []
  },
  "profiles": {
    "basic": {
      "performanceMode": "conservative",
      "outputPreset": "low",
      "effects": [
        { "id": "soft-beauty", "kind": "beauty2d" }
      ],
      "fallback": null
    },
    "standard": {
      "performanceMode": "balanced",
      "outputPreset": "medium",
      "effects": [
        { "id": "soft-beauty", "kind": "beauty2d" },
        { "id": "studio-makeup", "kind": "makeup" }
      ],
      "fallback": "basic"
    },
    "gan-showcase": {
      "performanceMode": "quality",
      "outputPreset": "high",
      "effects": [
        { "id": "portrait-style-a", "kind": "gan" }
      ],
      "fallback": "standard"
    }
  }
}

Names such as conservative and low are application-level keys. Your native adapter might map them to different SDK settings on Android, iOS, or another supported platform.

The important part is the graph:

high → gan-showcase → standard → basic
mid  → standard ───────────────→ basic
low  → basic

A GAN profile can fail without forcing the application to improvise. Its fallback is already a reviewed product decision.

Validate the graph before merge

Create validate-policy.mjs:

import { readFile, writeFile } from "node:fs/promises";
import { pathToFileURL } from "node:url";

const COST = {
  beauty2d: 0,
  sticker2d: 1,
  makeup: 1,
  segmentation: 2,
  avatar3d: 3,
  gan: 3
};

export function validatePolicy(policy) {
  const errors = [];
  const profiles = policy?.profiles ?? {};
  const entries = policy?.entryByTier ?? {};
  const rules = policy?.tierRules ?? {};

  if (policy?.version !== 1) {
    errors.push("version must be 1");
  }

  const profileCost = (name) => {
    const profile = profiles[name];
    if (!profile) return Number.POSITIVE_INFINITY;

    return profile.effects.reduce(
      (sum, effect) => sum + (COST[effect.kind] ?? 100),
      0
    );
  };

  for (const [name, profile] of Object.entries(profiles)) {
    if (!Array.isArray(profile.effects)) {
      errors.push(`${name}: effects must be an array`);
      continue;
    }

    const ids = new Set();

    for (const effect of profile.effects) {
      if (!effect.id || !effect.kind) {
        errors.push(`${name}: every effect needs id and kind`);
      }

      if (!(effect.kind in COST)) {
        errors.push(`${name}: unknown effect kind '${effect.kind}'`);
      }

      if (ids.has(effect.id)) {
        errors.push(`${name}: duplicate effect id '${effect.id}'`);
      }
      ids.add(effect.id);
    }

    if (profile.fallback !== null && !profiles[profile.fallback]) {
      errors.push(`${name}: fallback '${profile.fallback}' does not exist`);
    }

    if (
      profile.fallback !== null &&
      profiles[profile.fallback] &&
      profileCost(profile.fallback) >= profileCost(name)
    ) {
      errors.push(`${name}: fallback must have a lower relative cost`);
    }
  }

  for (const [tier, entry] of Object.entries(entries)) {
    if (!profiles[entry]) {
      errors.push(`${tier}: entry profile '${entry}' does not exist`);
      continue;
    }

    const prohibited = new Set(rules[tier] ?? []);
    const visited = new Set();
    let current = entry;

    while (current !== null) {
      if (visited.has(current)) {
        errors.push(`${tier}: fallback cycle reaches '${current}'`);
        break;
      }
      visited.add(current);

      const profile = profiles[current];
      if (!profile) break;

      for (const effect of profile.effects) {
        if (prohibited.has(effect.kind)) {
          errors.push(
            `${tier}: profile '${current}' uses prohibited '${effect.kind}'`
          );
        }
      }

      current = profile.fallback;
    }
  }

  return {
    ok: errors.length === 0,
    checkedProfiles: Object.keys(profiles).length,
    checkedTiers: Object.keys(entries).length,
    errors
  };
}

async function main() {
  const file = process.argv[2] ?? "beauty-policy.json";
  const policy = JSON.parse(await readFile(file, "utf8"));
  const report = validatePolicy(policy);

  await writeFile(
    "beauty-policy-report.json",
    JSON.stringify(report, null, 2) + "\n"
  );

  if (!report.ok) {
    console.error("Beauty policy rejected:");
    for (const error of report.errors) console.error(`- ${error}`);
    process.exitCode = 1;
    return;
  }

  console.log(
    `Beauty policy accepted: ${report.checkedProfiles} profiles, ` +
    `${report.checkedTiers} tiers`
  );
}

if (import.meta.url === pathToFileURL(process.argv[1]).href) {
  await main();
}

The cost values are intentionally ordinal. They are not Tencent RTC performance measurements. Their purpose is to enforce one local invariant: a fallback must be simpler than the profile it replaces.

Run the validator:

npm run validate

Expected output:

Beauty policy accepted: 3 profiles, 3 tiers

Now introduce a production-risking mistake:

"low": "gan-showcase"

The command should fail with an actionable reason instead of merely sending a generic workflow failure notification:

Beauty policy rejected:
- low: profile 'gan-showcase' uses prohibited 'gan'
- low: profile 'standard' uses prohibited 'makeup'

That second error follows from our sample policy because the low tier prohibits anything listed in its rule. Adjust tierRules to match your measured and reviewed policy; do not copy these categories as universal hardware facts.

Put the same check in GitHub Actions

Create .github/workflows/beauty-policy.yml:

name: Validate Beauty AR policy

on:
  pull_request:
    paths:
      - "beauty-policy.json"
      - "validate-policy.mjs"
      - "validate-policy.test.mjs"
      - ".github/workflows/beauty-policy.yml"
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "22"

      - name: Run policy tests
        run: npm test

      - name: Validate production policy
        run: npm run validate

      - name: Publish validation report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: beauty-policy-report
          path: beauty-policy-report.json
          if-no-files-found: warn

Notice what is absent: a daily schedule. A scheduled job is useful when an external dependency can drift, but this validator only checks repository state. Running it every night would create noise without finding a new class of failure.

If you later validate a remote asset registry or remotely hosted policy, a schedule may become justified. Give that check its own timeout and distinguish “registry unavailable” from “policy invalid.”

Test the dangerous configuration changes

Create validate-policy.test.mjs:

import test from "node:test";
import assert from "node:assert/strict";
import { readFile } from "node:fs/promises";
import { validatePolicy } from "./validate-policy.mjs";

const original = JSON.parse(
  await readFile(new URL("./beauty-policy.json", import.meta.url), "utf8")
);

const copy = () => structuredClone(original);

test("accepts the reviewed policy", () => {
  assert.equal(validatePolicy(copy()).ok, true);
});

test("rejects GAN as the low-tier entry", () => {
  const policy = copy();
  policy.entryByTier.low = "gan-showcase";

  const result = validatePolicy(policy);

  assert.equal(result.ok, false);
  assert.ok(result.errors.some((e) => e.includes("prohibited 'gan'")));
});

test("rejects a fallback cycle", () => {
  const policy = copy();
  policy.profiles.basic.fallback = "gan-showcase";

  const result = validatePolicy(policy);

  assert.equal(result.ok, false);
  assert.ok(
    result.errors.some(
      (e) => e.includes("fallback cycle") || e.includes("lower relative cost")
    )
  );
});

test("rejects a missing fallback profile", () => {
  const policy = copy();
  policy.profiles["gan-showcase"].fallback = "does-not-exist";

  const result = validatePolicy(policy);

  assert.equal(result.ok, false);
  assert.ok(result.errors.some((e) => e.includes("does not exist")));
});

Run everything locally:

npm test
npm run validate

CI now proves that the rollout graph is structurally safe. It does not prove that an asset can load, tracking will be stable, or the selected output settings will meet a frame-rate objective on real hardware. Those belong in device testing.

Apply profiles through explicit runtime states

A valid policy can still encounter missing assets, initialization errors, or device pressure. The runtime needs to expose that distinction.

Create runtime.mjs:

export class BeautyProfileController {
  #adapter;
  #policy;
  #revision = 0;
  #queue = Promise.resolve();

  state = { kind: "idle" };

  constructor(adapter, policy, onState = () => {}) {
    this.#adapter = adapter;
    this.#policy = policy;
    this.onState = onState;
  }

  applyTier(tier) {
    const revision = ++this.#revision;

    this.#queue = this.#queue.then(() => this.#run(tier, revision));
    return this.#queue;
  }

  async #run(tier, revision) {
    const entry = this.#policy.entryByTier[tier];

    if (!entry) {
      return this.#set({ kind: "blocked", reason: "unknown-tier", tier });
    }

    this.#set({ kind: "resolving", tier, profile: entry });

    let current = entry;
    let degraded = false;
    const failures = [];

    while (current !== null) {
      if (revision !== this.#revision) return this.state;

      const profile = this.#policy.profiles[current];
      this.#set({ kind: "applying", tier, profile: current, degraded });

      try {
        // These are application-owned adapter methods, not SDK API names.
        await this.#adapter.disableAllEffects();
        await this.#adapter.configureOutput(profile.outputPreset);
        await this.#adapter.setPerformanceMode(profile.performanceMode);

        for (const effect of profile.effects) {
          await this.#adapter.enableEffect(effect);
        }

        if (revision !== this.#revision) return this.state;

        return this.#set({
          kind: degraded ? "degraded" : "ready",
          tier,
          profile: current,
          failures
        });
      } catch (error) {
        failures.push({
          profile: current,
          message: error instanceof Error ? error.message : String(error)
        });
        degraded = true;
        current = profile.fallback;
      }
    }

    await this.#adapter.disableAllEffects().catch(() => {});

    return this.#set({
      kind: "blocked",
      tier,
      reason: "no-profile-could-be-applied",
      failures
    });
  }

  #set(next) {
    this.state = next;
    this.onState(next);
    return next;
  }
}

The adapter boundary might look like this:

const beautyAdapter = {
  async disableAllEffects() {
    // Map to the documented cleanup operations for your platform.
  },

  async configureOutput(outputPreset) {
    // Map your preset to the reviewed resolution/frame-rate policy.
  },

  async setPerformanceMode(performanceMode) {
    // Map the application key to the supported platform configuration.
  },

  async enableEffect(effect) {
    // Resolve effect.id and apply it through the platform integration.
  }
};

Do not copy those method names into SDK calls. They are a narrow port that prevents platform-specific code from becoming the source of rollout policy.

The state distinction also gives the UI honest options:

State	UI behavior
`resolving`	Keep controls disabled briefly while selecting the profile
`applying`	Show that the requested look is being prepared
`ready`	Show the selected effect as active
`degraded`	Explain that a compatible effect was substituted
`blocked`	Show an effects-unavailable state rather than pretending success

Whether the camera remains available when all effects fail is a separate consent and product decision. Do not silently treat raw camera output as the universal fallback.

How to choose a tier without inventing a universal benchmark

Use a two-stage decision:

1. Establish a conservative initial classification

Base it on signals your platform can obtain reliably and on a device matrix your team has actually tested. Unknown devices should enter a conservative profile rather than receiving GAN merely because they are absent from a deny list.

2. Confirm the classification with session measurements

Observe the rendered result, not just whether configuration calls succeeded. Depending on your platform, useful application measurements can include:

delivered or rendered frame cadence;
sustained frame gaps;
main-thread pressure;
thermal or memory warnings exposed by the operating system;
repeated renderer or asset-loading failures.

Define thresholds from your own supported-device tests. The official guide provides the optimization direction, but it does not justify one universal frame-rate threshold for every application.

For a simpler and more predictable UX, make degradation one-way during a session. Once a GAN profile falls back to standard, do not automatically oscillate back every time a short measurement window improves. Reconsider the tier on the next session or after an explicit user retry.

The trade-off is straightforward:

Automatic upgrade may restore richer effects sooner, but risks visible switching and repeated asset work.
Session-sticky fallback is less ambitious, but easier to explain, test, and support.

Failures CI cannot settle for you

The policy passes, but the GAN asset is unavailable

The static validator checks references and transitions, not remote availability. Add a staging check that resolves every production asset identifier. Keep availability errors separate from policy errors so an outage does not encourage someone to weaken the tier rules.

At runtime, gan-showcase should fail into standard. Record which profile failed and which one became active.

A remote configuration bypasses the repository

If production policy can be edited elsewhere, a green pull request check is not sufficient. Run the same validator in the publishing service and again when the client receives a new policy. Reject invalid revisions while preserving the last known-good policy.

Include a policy revision in logs so a device report can be tied to the configuration that produced it.

The fallback itself fails

A fallback is not guaranteed merely because it is cheaper. The controller continues until it reaches a working terminal profile. If basic also fails, it enters blocked and attempts to disable effects.

That state needs a user-facing outcome. “Effect unavailable” is more truthful than leaving a spinner active indefinitely.

Two profile requests arrive quickly

The sample controller serializes adapter operations and assigns every request a revision. This avoids concurrent calls fighting over renderer state. The cost is that a new request can wait for an older adapter operation to settle.

If your platform provides documented cancellation semantics, you can add cancellation inside the adapter. Do not simulate cancellation by ignoring a promise while allowing its side effects to keep modifying the renderer.

The GitHub Action fails repeatedly

A workflow failure should identify a policy invariant, not become background email noise. Keep the validation local and deterministic, publish the report even on failure, use a timeout, and avoid a schedule unless an external input can actually drift.

Release verification checklist

Before enabling the GAN profile for a production cohort, verify all three layers.

Repository policy

[ ] Every tier has an existing entry profile.
[ ] Low and mid tiers cannot reach prohibited effects through fallback chains.
[ ] Every fallback has a lower application-defined relative cost.
[ ] Every chain terminates without a cycle.
[ ] Pull requests run both tests and production-policy validation.

Runtime behavior

[ ] A failed GAN application reaches the expected cheaper profile.
[ ] The UI distinguishes ready, degraded, and blocked.
[ ] Rapid profile requests cannot leave mixed effects active.
[ ] An unknown tier fails conservatively.
[ ] A total effect failure follows an explicit camera and consent policy.

Real-device verification

[ ] Tests include the actual camera, output settings, and effect combination used in sessions.
[ ] Device-tier thresholds come from measured supported hardware.
[ ] Asset-loading failure is tested separately from sustained performance pressure.
[ ] The active policy revision and selected profile are observable.
[ ] Degradation does not oscillate repeatedly during one session.

The useful reframing

You do not need to prove that every device can run the most impressive Beauty AR effect. You need to prove that every supported device has a reviewed path when it cannot.

That is the difference between a demo and an implementation: the demo showcases the successful state; the implementation names all the states around it, assigns authority to configuration, and makes failure reproducible before release.

Discussion

Would you keep Beauty AR fallback sticky for the whole session, or allow a user-triggered retry after the device recovers? The answer depends less on rendering ambition than on how visible and disruptive switching profiles is in your experience.

Relationship disclosure: I have a connection to Tencent RTC, and I used the official Tencent RTC documentation linked above as the implementation reference for this article.