DEV Community: LunarDrift

The Filter Changed After the User Tapped Off: Race-Proof Tencent RTC Beauty AR

LunarDrift — Sun, 08 Nov 2026 17:10:43 +0000

A Beauty AR demo usually has one comfortable sequence: open the camera, select an effect, and admire the result.

Production users are less cooperative. They tap three effects quickly. They withdraw consent while an effect is loading. A low-end device cannot sustain a segmentation or GAN workload. An asynchronous callback then completes late and applies something the user already turned off.

That creates a tension bigger than rendering: who is authoritative—the computer-vision pipeline or the person looking at the preview?

The answer should be encoded, not implied. In this tutorial, we will build a small TypeScript control plane where:

the latest user intent wins;
consent withdrawal immediately hides processed output;
expensive effects can resolve to an explicit fallback;
stale asynchronous work cannot become the final state;
adapter failures return to unmodified video instead of leaving the UI ambiguous.

Tencent RTC Beauty AR supports real-time capabilities including beauty filters, makeup, stickers, virtual backgrounds, avatars, gesture recognition, and image/video enhancement. Its official documentation also recommends adapting expensive segmentation, 3D, and GAN effects for constrained devices. See the Beauty AR overview and Low-End Device Performance Optimization Practice Guide.

This tutorial deliberately does not invent SDK method names. We will build an application-owned coordinator with a narrow adapter that you can map to the documented Beauty AR integration used by your project.

The failure timeline

Consider this sequence:

T0  User selects a GAN effect
T1  The app starts preparing its resources
T2  User taps “Off”
T3  The UI changes to Off
T4  The old preparation finishes
T5  The GAN effect is applied anyway

A boolean such as beautyEnabled cannot represent this correctly. It says nothing about which request is current, whether work is in flight, or whether processed frames may still be published.

We need two independent controls:

Intent control: a monotonically increasing version makes old requests stale.
Output control: turning an effect off or withdrawing consent immediately holds processed output while cleanup catches up.

The second control matters because cancellation is not magic. An SDK or GPU operation may already be executing when the application asks it to stop.

Define the observable contract

The UI should render the coordinator's state rather than reconstructing state from button clicks:

type ViewState =
  | { kind: "ready"; active: "off" }
  | { kind: "preparing"; requested: EffectId; resolved: EffectId }
  | { kind: "active"; requested: EffectId; active: EffectId; degraded: boolean }
  | { kind: "failed"; requested: EffectId; message: string };

requested and active are intentionally separate. If someone selects a virtual background but the device policy resolves it to a lighter beauty effect, the application must not pretend the original effect is active.

Here is the behavior we will enforce:

Event	Immediate behavior	Eventual behavior
A newer effect is selected	Mark the previous preparation stale	Apply only the latest resolved effect
Off is selected	Hold processed output	Clear the effect and release raw video
Consent is withdrawn	Hold processed output immediately	Clear the effect; require a new opt-in before reuse
Requested effect exceeds the device budget	Show the resolved fallback	Apply the fallback or remain off
Preparation fails	Keep the failed request visible	Clear processing and return to raw video
Apply fails after preparation	Do not report the effect as active	Clear processing and return to raw video

Holding output might appear as a frozen preview, placeholder, or temporary camera pause depending on your product. That is an application decision. The invariant is that a known-unwanted processed frame must not be treated as acceptable merely because cleanup is asynchronous.

Create the project

mkdir beauty-intent-coordinator
cd beauty-intent-coordinator
npm init -y
npm install --save-dev typescript tsx @types/node
mkdir src test

Add the following implementation as src/coordinator.ts.

export type EffectId = "off" | "soft-beauty" | "virtual-bg" | "gan-look";

type EffectDefinition = {
  id: EffectId;
  needsSegmentation: boolean;
  needsGan: boolean;
  fallback: EffectId;
};

const EFFECTS: Record<EffectId, EffectDefinition> = {
  off: {
    id: "off",
    needsSegmentation: false,
    needsGan: false,
    fallback: "off",
  },
  "soft-beauty": {
    id: "soft-beauty",
    needsSegmentation: false,
    needsGan: false,
    fallback: "off",
  },
  "virtual-bg": {
    id: "virtual-bg",
    needsSegmentation: true,
    needsGan: false,
    fallback: "soft-beauty",
  },
  "gan-look": {
    id: "gan-look",
    needsSegmentation: false,
    needsGan: true,
    fallback: "soft-beauty",
  },
};

export type DevicePolicy = {
  segmentationAllowed: boolean;
  ganAllowed: boolean;
  budget: "normal" | "constrained";
};

export type ViewState =
  | { kind: "ready"; active: "off" }
  | { kind: "preparing"; requested: EffectId; resolved: EffectId }
  | {
      kind: "active";
      requested: EffectId;
      active: EffectId;
      degraded: boolean;
    }
  | { kind: "failed"; requested: EffectId; message: string };

export interface BeautyAdapter {
  /** Fetch or prepare resources. It should honor cancellation where possible. */
  prepare(effect: EffectId, signal: AbortSignal): Promise<void>;

  /** Commit one prepared effect to the processing pipeline. */
  apply(effect: EffectId): Promise<void>;

  /** Remove appearance processing and return to unmodified video. */
  clear(): Promise<void>;
}

export interface OutputGate {
  /** Synchronously prevent processed output from being shown or published. */
  hold(reason: "off-requested" | "consent-withdrawn"): void;

  /** Release the unmodified camera path after processing has been cleared. */
  releaseRaw(): void;
}

export class BeautyCoordinator {
  private consent = false;
  private desired: EffectId = "off";
  private version = 0;
  private preparation?: AbortController;
  private work: Promise<void> = Promise.resolve();

  private state: ViewState = { kind: "ready", active: "off" };

  constructor(
    private readonly adapter: BeautyAdapter,
    private readonly gate: OutputGate,
    private policy: DevicePolicy,
  ) {}

  getState(): ViewState {
    return this.state;
  }

  setConsent(granted: boolean): void {
    if (granted === this.consent) return;

    this.consent = granted;
    this.version += 1;
    this.preparation?.abort();

    if (!granted) {
      // Consent withdrawal invalidates the old preference. Re-enabling consent
      // will not silently restore a previous appearance effect.
      this.desired = "off";
      this.gate.hold("consent-withdrawn");
    }

    this.enqueue();
  }

  select(effect: EffectId): void {
    if (effect !== "off" && !this.consent) {
      this.state = {
        kind: "failed",
        requested: effect,
        message: "Consent is required before applying an appearance effect.",
      };
      return;
    }

    this.desired = effect;
    this.version += 1;
    this.preparation?.abort();

    if (effect === "off") {
      this.gate.hold("off-requested");
    }

    this.enqueue();
  }

  updatePolicy(policy: DevicePolicy): void {
    this.policy = policy;
    this.version += 1;
    this.preparation?.abort();
    this.enqueue();
  }

  async idle(): Promise<void> {
    await this.work;
  }

  private enqueue(): void {
    // One writer reaches the adapter at a time. Each queued reconciliation
    // reads the latest intent, so bursts naturally coalesce.
    this.work = this.work.then(() => this.reconcile());
  }

  private resolve(requested: EffectId): EffectId {
    const effect = EFFECTS[requested];

    if (requested === "off") return "off";

    if (this.policy.budget === "constrained") {
      if (effect.needsGan || effect.needsSegmentation) {
        return effect.fallback;
      }
    }

    if (effect.needsGan && !this.policy.ganAllowed) {
      return effect.fallback;
    }

    if (effect.needsSegmentation && !this.policy.segmentationAllowed) {
      return effect.fallback;
    }

    return requested;
  }

  private async reconcile(): Promise<void> {
    const operationVersion = this.version;
    const requested = this.desired;

    if (!this.consent || requested === "off") {
      try {
        await this.adapter.clear();
        this.state = { kind: "ready", active: "off" };
        this.gate.releaseRaw();
      } catch (error) {
        this.state = {
          kind: "failed",
          requested: "off",
          message: `Could not clear the effect: ${messageOf(error)}`,
        };
        // Do not release processed output when clear has not been confirmed.
      }
      return;
    }

    const resolved = this.resolve(requested);
    this.state = { kind: "preparing", requested, resolved };

    const abort = new AbortController();
    this.preparation = abort;

    try {
      await this.adapter.prepare(resolved, abort.signal);

      // Preparation completed, but another user action may now be authoritative.
      if (operationVersion !== this.version) return;

      await this.adapter.apply(resolved);

      // apply() might not be cancellable. If intent changed while it ran, leave
      // final reconciliation to the queued operation.
      if (operationVersion !== this.version) return;

      this.state = {
        kind: "active",
        requested,
        active: resolved,
        degraded: requested !== resolved,
      };
    } catch (error) {
      if (operationVersion !== this.version || isAbort(error)) return;

      try {
        await this.adapter.clear();
        this.gate.releaseRaw();
      } catch {
        // Keep the output gate's existing safety posture if cleanup also fails.
      }

      this.state = {
        kind: "failed",
        requested,
        message: `Effect unavailable: ${messageOf(error)}`,
      };
    } finally {
      if (this.preparation === abort) this.preparation = undefined;
    }
  }
}

function isAbort(error: unknown): boolean {
  return error instanceof Error && error.name === "AbortError";
}

function messageOf(error: unknown): string {
  return error instanceof Error ? error.message : "unknown error";
}

Several choices here are deliberate:

Selection and consent are not the same state. Device support cannot grant permission.
Consent withdrawal forgets the old effect. Granting consent again does not silently restore it.
Adapter calls are serialized. Two asynchronous effect commits cannot race as independent writers.
Preparation is cancellable. Resource work can stop early where the underlying implementation supports it.
Application is still version-checked. Cancellation alone is insufficient because commit operations may be non-cancellable.
Cleanup must succeed before raw output is released. A failed clear() is not equivalent to an effect being off.

Reproduce the races

Create test/coordinator.test.ts:

import assert from "node:assert/strict";
import test from "node:test";
import {
  BeautyAdapter,
  BeautyCoordinator,
  EffectId,
  OutputGate,
} from "../src/coordinator.js";

const sleep = (ms: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, ms));

class FakeAdapter implements BeautyAdapter {
  prepared: EffectId[] = [];
  applied: EffectId[] = [];
  clears = 0;
  prepareDelay = 0;
  applyDelay = 0;
  failApply = false;

  async prepare(effect: EffectId, signal: AbortSignal): Promise<void> {
    this.prepared.push(effect);

    await new Promise<void>((resolve, reject) => {
      const timer = setTimeout(resolve, this.prepareDelay);
      signal.addEventListener(
        "abort",
        () => {
          clearTimeout(timer);
          const error = new Error("aborted");
          error.name = "AbortError";
          reject(error);
        },
        { once: true },
      );
    });
  }

  async apply(effect: EffectId): Promise<void> {
    await sleep(this.applyDelay);
    if (this.failApply) throw new Error("GPU setup failed");
    this.applied.push(effect);
  }

  async clear(): Promise<void> {
    this.clears += 1;
  }
}

class FakeGate implements OutputGate {
  held = false;
  reasons: string[] = [];

  hold(reason: "off-requested" | "consent-withdrawn"): void {
    this.held = true;
    this.reasons.push(reason);
  }

  releaseRaw(): void {
    this.held = false;
  }
}

const normalPolicy = {
  segmentationAllowed: true,
  ganAllowed: true,
  budget: "normal" as const,
};

test("latest selection wins while preparation is in flight", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  adapter.prepareDelay = 20;

  const coordinator = new BeautyCoordinator(adapter, gate, normalPolicy);
  coordinator.setConsent(true);
  coordinator.select("virtual-bg");

  await sleep(5); // Let virtual-bg preparation begin.
  coordinator.select("gan-look");
  await coordinator.idle();

  assert.deepEqual(adapter.applied, ["gan-look"]);
  assert.deepEqual(coordinator.getState(), {
    kind: "active",
    requested: "gan-look",
    active: "gan-look",
    degraded: false,
  });
});

test("consent withdrawal holds output before a non-cancellable apply ends", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  adapter.applyDelay = 25;

  const coordinator = new BeautyCoordinator(adapter, gate, normalPolicy);
  coordinator.setConsent(true);
  coordinator.select("gan-look");

  await sleep(5); // apply() is now in flight.
  coordinator.setConsent(false);

  assert.equal(gate.held, true);
  assert.equal(gate.reasons.at(-1), "consent-withdrawn");

  await coordinator.idle();

  assert.deepEqual(coordinator.getState(), { kind: "ready", active: "off" });
  assert.equal(gate.held, false);
  assert.ok(adapter.clears > 0);
});

test("a constrained budget resolves GAN to the declared fallback", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  const coordinator = new BeautyCoordinator(adapter, gate, {
    segmentationAllowed: true,
    ganAllowed: true,
    budget: "constrained",
  });

  coordinator.setConsent(true);
  coordinator.select("gan-look");
  await coordinator.idle();

  assert.deepEqual(adapter.applied, ["soft-beauty"]);
  assert.deepEqual(coordinator.getState(), {
    kind: "active",
    requested: "gan-look",
    active: "soft-beauty",
    degraded: true,
  });
});

test("an apply failure returns to raw video and remains visible", async () => {
  const adapter = new FakeAdapter();
  const gate = new FakeGate();
  adapter.failApply = true;

  const coordinator = new BeautyCoordinator(adapter, gate, normalPolicy);
  coordinator.setConsent(true);
  coordinator.select("virtual-bg");
  await coordinator.idle();

  assert.equal(coordinator.getState().kind, "failed");
  assert.ok(adapter.clears > 0);
  assert.equal(gate.held, false);
});

Run the suite:

npx tsx --test test/*.test.ts

These tests verify protocol behavior rather than image quality. Visual quality still requires real-device review, but it should not be used as a substitute for testing control-flow races.

Connect the adapter without guessing SDK APIs

Keep the Tencent RTC integration behind BeautyAdapter:

class TencentBeautyAdapter implements BeautyAdapter {
  constructor(
    private readonly beautyRuntime: YourDocumentedBeautyIntegration,
  ) {}

  async prepare(effect: EffectId, signal: AbortSignal): Promise<void> {
    // Map your application's effect ID to the documented resource-loading path.
    // If that path cannot consume AbortSignal, check signal.aborted before and
    // after loading and let the coordinator reject stale completion.
  }

  async apply(effect: EffectId): Promise<void> {
    // Map exactly one resolved effect to your documented Beauty AR setup.
  }

  async clear(): Promise<void> {
    // Remove appearance processing using the documented integration path.
  }
}

Do the same for OutputGate. It belongs at the point in your architecture where you can prevent processed frames from reaching the preview or publication path. Do not hide this behavior inside a button component; consent can change because of navigation, account state, or another product-level event.

The official low-end optimization guide discusses choosing suitable performance modes, disabling expensive segmentation or 3D/GAN effects, and controlling resolution and frame rate. Treat those as measurable deployment policies, not universal constants. This coordinator only chooses an effect workload. Your media configuration should separately own resolution and frame-rate decisions.

Decide the budget from evidence

Avoid classifying a device from a model name alone. Build your deployment policy from observed sessions and real-device testing.

Useful measurements include:

preview and published frame stability;
render or processing duration where observable;
thermal behavior over a representative session;
memory pressure during effect switching;
camera interruptions and application lifecycle changes;
whether audio or RTC behavior degrades when visual processing is enabled.

Then make one of three decisions for each effect-and-device class:

Allow: the effect stays within the accepted product budget.
Resolve to fallback: the requested effect is too expensive, but a declared lighter option is acceptable.
Keep off: neither the request nor its fallback meets the budget.

Do not silently label fallback as success. If gan-look resolves to soft-beauty, render that distinction in the UI and telemetry.

Hidden costs this design makes visible

Output gating can create a visual interruption

Immediately holding processed output is safer than displaying an effect after withdrawal, but it may produce a short freeze or placeholder. Product and design should choose that presentation explicitly.

Serialization can make switching feel slower

A single-writer pipeline sacrifices some apparent parallelism. In return, it prevents competing commits from owning the renderer. Preparation can still be optimized or cached, but commits should remain ordered.

Caches create another policy surface

Caching effect resources can improve repeat selection, but it also consumes memory and complicates invalidation. Cache ownership should not leak into the consent model: retaining a resource is not permission to reactivate it.

Graceful degradation increases the QA matrix

Every fallback adds states to verify: request, resolved effect, visible label, recovery, and telemetry. That is a real engineering cost. If a fallback cannot be explained or tested, keeping the feature off may be the better decision.

Where the AI is—and is not

Segmentation, tracking, enhancement, and GAN-based appearance effects can involve real-time computer vision. That is demonstrated capability, not authority.

The model or visual pipeline can transform pixels. It should not decide:

whether a person consented to appearance modification;
whether a fallback is aesthetically acceptable;
whether an effect should silently return after consent changes;
whether thermal, battery, or accessibility trade-offs are acceptable;
whether a processed image still represents the user as intended.

This reframes the anxiety around AI changing engineering roles. The valuable work does not disappear when a visual model becomes more capable. It moves toward defining invariants, measuring budgets, designing reversible controls, and testing the asynchronous boundaries where automated systems routinely fail.

Real-device verification pass

Before release, run this checklist on each supported capability tier:

[ ] Select three effects rapidly; only the final selection becomes active.
[ ] Select Off while preparation is running; the old effect never becomes the final visible state.
[ ] Withdraw consent during application; processed output is held immediately.
[ ] Grant consent again; the old effect does not reactivate automatically.
[ ] Deny GAN capability; the UI reports the actual fallback.
[ ] Deny segmentation capability; virtual background does not pretend to be active.
[ ] Force preparation failure; raw video remains available with a retry path.
[ ] Force apply failure; the application does not report success.
[ ] Force clear failure; processed output remains gated rather than falsely reporting Off.
[ ] Background and restore the application during preparation.
[ ] Test a representative-length session for heat, memory pressure, and frame stability.
[ ] Confirm that Beauty AR stress does not conceal media or audio failures elsewhere in the RTC experience.

Discussion: make the contract shared

A useful organizational change does not begin with announcing that AI will automate more work. It begins when product, engineering, QA, and design stop carrying incompatible assumptions.

For this feature, the shared artifact is the transition contract:

Product defines what each fallback means.
Design defines how gating and degradation are shown.
Engineering guarantees ordering and cleanup.
QA attacks the asynchronous boundaries.
Users remain the authority over whether appearance effects are active.

That is a more durable outcome than a flawless demo. The hard part of Beauty AR is not merely making an effect appear—it is ensuring that it disappears when the person says it should.

Disclosure: I contribute developer content for Tencent RTC. I used the official Tencent RTC Beauty AR documentation as the implementation reference for this article.

Turn a GAN Beauty Demo Into a Release Decision: Build an Evidence Gate for Tencent RTC Beauty AR

LunarDrift — Sat, 07 Nov 2026 17:08:27 +0000

A polished GAN beauty demo can create momentum—and an uncomfortable question for the engineers in the room:

Who decides whether this is actually ready to ship?

The model can generate an impressive effect. It cannot decide whether the visual result is respectful, whether the extra workload is acceptable on your supported devices, or whether an incomplete test run should count as evidence.

That uncertainty is not a sign that your role has become less relevant. It is a sign that the difficult work has moved. Instead of asking only whether the effect works, the team needs an explicit release contract covering performance, visual review, consent, failure behavior, and ownership.

In this tutorial, we will build that contract as a small TypeScript evidence gate for a Tencent RTC Beauty AR scenario. The gate will:

Compare a GAN candidate with a baseline on the same device.
Reject incomplete or incomparable measurements.
Keep performance evidence separate from human visual approval.
Produce one of four explicit release states.
Require a verified baseline fallback before approving the candidate.
Prevent a presentation or screenshot from becoming accidental release approval.

The code does not invent Tencent RTC SDK methods. It creates an application-owned test and release layer that you can connect to your actual Beauty AR integration.

The release question we are answering

Assume a team wants to add an optional GAN-based appearance effect to a live calling or streaming experience.

Tencent RTC Beauty AR supports real-time capabilities including 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

The low-end device optimization guide recommends treating effects as workloads. Depending on device capability, that can mean selecting an appropriate performance mode, controlling resolution and frame rate, or disabling expensive segmentation, 3D, and GAN effects:

https://trtc.io/document/66968

Those recommendations do not give every application one universal passing score. A live commerce stream, a casual call, and a recorded creator workflow may make different trade-offs.

Our application therefore defines its own release question:

Does the candidate retain enough of the baseline's measured rendering performance on every device in the declared release scope, pass visual review, preserve an off control, and recover to a verified baseline if activation fails?

The threshold belongs to the product team. It is not a Tencent RTC performance guarantee.

Turn the demo into an evidence artifact

A useful test run needs more than passed: true. It should identify:

The application and effect build.
The physical device or reproducible device class.
Whether the baseline or candidate was active.
The test scene and duration.
Observed frame-rate samples from application instrumentation.
Renderer errors and thermal warnings available to the host application.
Whether the user-facing off control was tested.
The human review result.
Whether the baseline fallback was verified.

Avoid retaining face images merely because the test harness can capture them. Performance samples and a reviewer decision may be sufficient. If visual artifacts must be stored, define participant consent, access, and deletion rules before recording.

Create the test project

mkdir beauty-release-gate
cd beauty-release-gate
npm init -y
npm install -D typescript vitest @types/node
npx tsc --init
mkdir src test

Update package.json:

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

Create src/model.ts:

export type Profile = "baseline" | "gan-candidate";

export type RunState =
  | "planned"
  | "running"
  | "complete"
  | "cancelled"
  | "invalid";

export type ReviewDecision =
  | "pending"
  | "accepted"
  | "rejected";

export interface TestRun {
  id: string;
  deviceId: string;
  deviceClass: string;
  appBuild: string;
  effectBuild: string;
  sceneId: string;
  profile: Profile;
  state: RunState;

  // Values collected by the host application's instrumentation.
  observedFps: number[];
  rendererErrors: string[];
  thermalWarnings: number;

  offControlVerified: boolean;
  fallbackVerified: boolean;
  review: ReviewDecision;
}

export interface GatePolicy {
  requiredDeviceIds: string[];
  minimumFpsRetention: number;
  requireNoRendererErrors: boolean;
  requireNoThermalWarnings: boolean;
}

export type GateState =
  | "collecting-evidence"
  | "awaiting-human-review"
  | "approved"
  | "rejected";

export interface GateResult {
  state: GateState;
  reasons: string[];
}

There are two deliberate separations here.

First, complete does not mean accepted. A technically complete run can still fail either performance policy or human review.

Second, the baseline and candidate are separate records. That prevents a candidate measured on one device or scene from being compared with an unrelated baseline.

Make invalid evidence impossible to overlook

Create src/gate.ts:

import {
  GatePolicy,
  GateResult,
  TestRun,
} from "./model.js";

function median(values: number[]): number | undefined {
  if (values.length === 0) return undefined;

  const sorted = [...values].sort((a, b) => a - b);
  const middle = Math.floor(sorted.length / 2);

  return sorted.length % 2 === 0
    ? (sorted[middle - 1] + sorted[middle]) / 2
    : sorted[middle];
}

function comparable(a: TestRun, b: TestRun): boolean {
  return (
    a.deviceId === b.deviceId &&
    a.appBuild === b.appBuild &&
    a.effectBuild === b.effectBuild &&
    a.sceneId === b.sceneId
  );
}

export function evaluateGate(
  runs: TestRun[],
  policy: GatePolicy,
): GateResult {
  const reasons: string[] = [];
  let waitingForReview = false;

  for (const deviceId of policy.requiredDeviceIds) {
    const baseline = runs.find(
      run => run.deviceId === deviceId && run.profile === "baseline",
    );
    const candidate = runs.find(
      run => run.deviceId === deviceId && run.profile === "gan-candidate",
    );

    if (!baseline || !candidate) {
      reasons.push(`${deviceId}: baseline or candidate run is missing`);
      continue;
    }

    if (baseline.state !== "complete" || candidate.state !== "complete") {
      reasons.push(`${deviceId}: both runs must be complete`);
      continue;
    }

    if (!comparable(baseline, candidate)) {
      reasons.push(`${deviceId}: runs use different builds or scenes`);
      continue;
    }

    const baselineFps = median(baseline.observedFps);
    const candidateFps = median(candidate.observedFps);

    if (baselineFps === undefined || candidateFps === undefined) {
      reasons.push(`${deviceId}: frame-rate evidence is missing`);
      continue;
    }

    const retention = candidateFps / baselineFps;

    if (retention < policy.minimumFpsRetention) {
      reasons.push(
        `${deviceId}: FPS retention ${retention.toFixed(2)} is below ` +
        `${policy.minimumFpsRetention.toFixed(2)}`,
      );
    }

    if (
      policy.requireNoRendererErrors &&
      candidate.rendererErrors.length > 0
    ) {
      reasons.push(`${deviceId}: candidate reported renderer errors`);
    }

    if (
      policy.requireNoThermalWarnings &&
      candidate.thermalWarnings > 0
    ) {
      reasons.push(`${deviceId}: candidate reported thermal warnings`);
    }

    if (!candidate.offControlVerified) {
      reasons.push(`${deviceId}: user-facing off control was not verified`);
    }

    if (!candidate.fallbackVerified) {
      reasons.push(`${deviceId}: baseline fallback was not verified`);
    }

    if (candidate.review === "rejected") {
      reasons.push(`${deviceId}: human visual review rejected the result`);
    } else if (candidate.review === "pending") {
      waitingForReview = true;
    }
  }

  if (reasons.length > 0) {
    const incomplete = reasons.some(reason =>
      reason.includes("missing") ||
      reason.includes("must be complete") ||
      reason.includes("different builds"),
    );

    return {
      state: incomplete ? "collecting-evidence" : "rejected",
      reasons,
    };
  }

  if (waitingForReview) {
    return {
      state: "awaiting-human-review",
      reasons: ["Performance evidence passed; visual review is pending"],
    };
  }

  return {
    state: "approved",
    reasons: [],
  };
}

This gate treats missing data as missing data—not as a pass and not automatically as a product failure.

That distinction matters:

Collecting evidence means the test is incomplete or incomparable.
Awaiting human review means the measurable policy passed, but a person still needs to assess the result.
Rejected means complete evidence violated a release rule.
Approved means every declared requirement passed.

A team can now discuss the policy instead of arguing over whether a demo “felt smooth.”

Reproduce the disputed cases

Create test/gate.test.ts:

import { describe, expect, it } from "vitest";
import { evaluateGate } from "../src/gate.js";
import type { GatePolicy, TestRun } from "../src/model.js";

const policy: GatePolicy = {
  requiredDeviceIds: ["device-a"],

  // Example application policy, not a product guarantee.
  minimumFpsRetention: 0.85,
  requireNoRendererErrors: true,
  requireNoThermalWarnings: true,
};

function run(
  profile: TestRun["profile"],
  overrides: Partial<TestRun> = {},
): TestRun {
  return {
    id: `${profile}-run`,
    deviceId: "device-a",
    deviceClass: "release-matrix-entry-1",
    appBuild: "app-42",
    effectBuild: "effect-7",
    sceneId: "indoor-steady-light",
    profile,
    state: "complete",
    observedFps: profile === "baseline" ? [30, 30, 29] : [27, 27, 26],
    rendererErrors: [],
    thermalWarnings: 0,
    offControlVerified: true,
    fallbackVerified: true,
    review: profile === "baseline" ? "accepted" : "pending",
    ...overrides,
  };
}

describe("Beauty AR release gate", () => {
  it("does not turn performance evidence into visual approval", () => {
    const result = evaluateGate(
      [run("baseline"), run("gan-candidate")],
      policy,
    );

    expect(result.state).toBe("awaiting-human-review");
  });

  it("rejects a candidate that falls below the team's retention rule", () => {
    const candidate = run("gan-candidate", {
      observedFps: [20, 20, 19],
      review: "accepted",
    });

    const result = evaluateGate(
      [run("baseline"), candidate],
      policy,
    );

    expect(result.state).toBe("rejected");
    expect(result.reasons[0]).toContain("FPS retention");
  });

  it("does not compare different effect builds", () => {
    const candidate = run("gan-candidate", {
      effectBuild: "effect-8",
      review: "accepted",
    });

    const result = evaluateGate(
      [run("baseline"), candidate],
      policy,
    );

    expect(result.state).toBe("collecting-evidence");
  });

  it("requires a tested fallback before approval", () => {
    const candidate = run("gan-candidate", {
      review: "accepted",
      fallbackVerified: false,
    });

    const result = evaluateGate(
      [run("baseline"), candidate],
      policy,
    );

    expect(result.state).toBe("rejected");
    expect(result.reasons[0]).toContain("fallback");
  });

  it("approves only complete technical and human evidence", () => {
    const candidate = run("gan-candidate", {
      review: "accepted",
    });

    const result = evaluateGate(
      [run("baseline"), candidate],
      policy,
    );

    expect(result).toEqual({ state: "approved", reasons: [] });
  });
});

Run it:

npm test

The important test is not merely the happy path. It is the case where the measurements look acceptable but review is still pending. That is where an enthusiastic presentation can otherwise become an implicit approval.

Collect paired runs without biasing the result

A comparison is only useful when the runs are meaningfully comparable. Use this workflow for each physical device in your release matrix:

Confirm participant consent before enabling any appearance effect or recording visual evidence.
Record the application build, effect build, device identifier, and test scene.
Run the baseline for the configured duration.
Allow the device to return to the team's defined starting condition.
Run the GAN candidate in the same scene.
Repeat in the opposite order to expose warm-up or thermal-order bias.
Exercise the visible off control during the candidate run.
Force candidate activation to fail and verify restoration of the baseline.
Submit the visual result for human review.
Evaluate the complete device matrix rather than selecting the best run.

Lighting, camera movement, background complexity, and multiple effects can change the workload. Give each important combination a distinct sceneId instead of silently mixing its samples with an easier scene.

Do not use one median to hide an obviously unstable run. The example gate is intentionally small. A production policy can add duration requirements, variability checks, or sustained-window analysis, provided those rules are documented and tested.

Connect the gate to Beauty AR without guessing SDK APIs

The gate should not directly call a product-specific method. Put a narrow adapter around the Beauty AR integration used by your application:

export interface BeautyRendererPort {
  applyBaseline(): Promise<void>;
  applyGanCandidate(): Promise<void>;
}

export type RuntimeEffectState =
  | "off"
  | "applying-candidate"
  | "candidate-active"
  | "restoring-baseline"
  | "baseline-active"
  | "unavailable";

export interface ActivationResult {
  state: RuntimeEffectState;
  reason?: string;
}

export async function activateApprovedCandidate(
  renderer: BeautyRendererPort,
  releaseState: "approved" | "not-approved",
  consent: boolean,
): Promise<ActivationResult> {
  if (!consent) {
    return { state: "off", reason: "User consent is not active" };
  }

  if (releaseState !== "approved") {
    await renderer.applyBaseline();
    return {
      state: "baseline-active",
      reason: "GAN candidate is not approved for this release scope",
    };
  }

  try {
    await renderer.applyGanCandidate();
    return { state: "candidate-active" };
  } catch (candidateError) {
    try {
      await renderer.applyBaseline();
      return {
        state: "baseline-active",
        reason: "Candidate activation failed; baseline restored",
      };
    } catch (baselineError) {
      return {
        state: "unavailable",
        reason: "Candidate and baseline activation both failed",
      };
    }
  }
}

BeautyRendererPort is application code, not a claimed Tencent RTC API. Its implementation should map to the documented Beauty AR integration in your target platform.

The runtime rule is intentionally conservative: failure does not trigger an endless candidate retry loop. The session returns to the verified baseline. If even that fails, the UI should state that the appearance effect is unavailable while leaving the underlying call or stream usable where possible.

Failure modes to decide before the review meeting

Failure	Gate or runtime state	Required response
Candidate run exists but baseline is missing	`collecting-evidence`	Run the matching baseline; do not estimate it from another device.
Candidate and baseline use different builds	`collecting-evidence`	Repeat the pair using identical builds and scenes.
Instrumentation returns no samples	`collecting-evidence`	Repair or replace the probe; absence of data is not success.
Candidate exceeds the team's workload budget	`rejected`	Optimize, narrow the supported scope, or omit the GAN effect.
Visual result is technically fast but unacceptable	`rejected`	Revise or remove the effect; performance cannot overrule review.
Reviewers disagree	`awaiting-human-review`	Use the named product or safety owner rather than averaging opinions anonymously.
User withdraws consent	`off`	Stop applying the effect and follow the application's retention policy for test artifacts.
Candidate activation fails at runtime	`baseline-active`	Restore the verified baseline and record the failure reason.
Candidate and baseline both fail	`unavailable`	Disable the appearance effect and keep the state visible.

For device classes that cannot sustain the intended workload, the official optimization guidance supports reducing the effect workload—for example, by controlling resolution and frame rate or excluding expensive segmentation, 3D, and GAN effects. That reduced configuration needs its own evidence. Do not call it a fallback merely because it exists in configuration.

What the AI contributes—and what remains a human decision

A GAN effect can contribute sophisticated real-time image transformation. That demonstrated capability is useful, but it does not settle the release decision.

Humans still need to decide:

Whether the effect should be offered at all in the product context.
Whether it is opt-in, remembered, or reset between sessions.
Which visual changes are acceptable.
Which physical devices belong in the supported scope.
How much quality or frame-rate retention the experience requires.
What happens when the effect fails halfway through a live session.
Whether captured review material should be stored.

This is a more useful framing than asking whether AI removes the need for engineers or testers. The valuable skill is no longer just spotting one broken frame. It is converting ambiguous quality expectations into observable states, comparable evidence, and a release rule that the organization can inspect.

Release verification checklist

Before marking a GAN candidate as approved, verify that:

[ ] Every device in the declared release scope has paired baseline and candidate runs.
[ ] Each pair uses the same application build, effect build, and scene.
[ ] Measurements come from real application instrumentation, not visual guesswork.
[ ] The test order is alternated or otherwise controlled for warm-up and heat.
[ ] Missing samples produce an incomplete state rather than a pass.
[ ] Renderer errors and available thermal signals are retained with the run.
[ ] The visible off control is exercised during a live effect session.
[ ] Consent withdrawal removes the effect without requiring a restart.
[ ] Human visual approval is recorded separately from performance evidence.
[ ] Candidate activation failure restores the verified baseline.
[ ] Baseline failure produces a visible unavailable state.
[ ] Any lower-workload configuration has its own test evidence.
[ ] Stored visual artifacts have an explicit access and deletion policy.
[ ] The release decision identifies its owner and the exact approved build.

The organizational change worth keeping

An AI presentation can be valuable without becoming an automatic mandate to ship. The healthiest change is not “the model impressed the room, so reorganize around it.” It is replacing informal confidence with an explicit decision process.

For Beauty AR, that means treating GAN effects as both computer-vision features and real-time workloads. The model produces the effect. Instrumentation reports what happened. A gate checks the declared policy. A person remains accountable for whether the result belongs in the product.

That is not resistance to AI. It is how a capable prototype becomes an operable live feature.

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

Benchmark the Moderator, Not the Demo: A Safer AI Voice Room with Tencent RTC

LunarDrift — Fri, 06 Nov 2026 02:51:06 +0000

A moderation bot can look remarkably capable in a controlled voice-room demo. The difficult question is what happens when its recommendation is late, the reported speaker has already left the mic, or the bot attempts to speak without a seat.

That creates a real tension for developers: you may want AI to reduce a moderator’s workload, but you do not want model confidence to become room authority.

The useful reframe is to stop evaluating the system as one intelligent character. Evaluate it as a protocol with separate responsibilities:

Tencent RTC carries the live audio experience.
Room and seat state determine who may publish audio.
Speech recognition, if used, produces text for review.
A model may classify or recommend an action.
A human moderator owns consequential decisions.
The application server validates and applies approved actions.

In this tutorial, we will build the application-owned control layer around that protocol. The result is a small moderation benchmark you can run repeatedly before connecting a model or live room.

The behavior we want to prove

Our example room has human speakers and an optional AI moderator participant. The AI can submit a recommendation such as “mute this occupied seat,” but it cannot approve the recommendation—even if its participant role is labeled moderator.

If the AI needs to read a warning aloud, it follows the same floor rules as everyone else:

It must be assigned an occupied mic seat.
That seat must not be muted.
The room must still be open.
A human must have approved the warning workflow.

This separates two commonly conflated permissions:

Moderation authority: who may approve a room action.
Audio capability: who currently has a seat and may publish sound.

Tencent RTC’s Voice Chat Room material describes the scenario in terms of rooms, mic seats, audio streams, moderation, and related room capabilities. Its implementation guide builds room and mic-seat behavior around LiveListStore and LiveSeatStore. Those documented concepts are the integration boundary used here:

We will not invent SDK methods. Instead, the tutorial creates a testable domain layer that an adapter can connect to the documented stores and operations used by your application.

Create the project

Use a recent Node.js installation, then create a TypeScript project with Vitest:

mkdir voice-room-moderation-bench
cd voice-room-moderation-bench
npm init -y
npm install --save-dev typescript vitest @types/node
npm pkg set scripts.test="vitest run"
npx tsc --init
mkdir src

Add this minimal compiler configuration to tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Represent authority and seat state separately

Create src/moderation.ts:

export type ParticipantKind = "human" | "ai";
export type ParticipantRole = "host" | "moderator" | "member";
export type RoomPhase = "open" | "closing" | "closed";
export type ModerationAction = "mute" | "removeFromSeat";

export interface Participant {
  id: string;
  kind: ParticipantKind;
  role: ParticipantRole;
}

export interface Seat {
  id: string;
  occupantId: string | null;
  muted: boolean;

  // Application-owned revision assigned whenever a fresh seat
  // snapshot is accepted. It is not presented as an SDK field.
  revision: number;
}

export type ProposalStatus =
  | "pending"
  | "applying"
  | "awaitingObservation"
  | "verified"
  | "failed"
  | "uncertain"
  | "dismissed";

export interface ModerationProposal {
  id: string;
  sourceId: string;
  targetId: string;
  action: ModerationAction;
  reason: string;
  evidenceRefs: string[];
  expectedSeatId: string;
  expectedSeatRevision: number;
  expiresAt: number;
  status: ProposalStatus;
  operationId?: string;
  reviewedBy?: string;
  failureReason?: string;
}

export interface RoomState {
  phase: RoomPhase;
  participants: Record<string, Participant>;
  seats: Record<string, Seat>;
  proposals: Record<string, ModerationProposal>;
}

export interface ApplyModerationEffect {
  type: "APPLY_MODERATION";
  operationId: string;
  proposalId: string;
  action: ModerationAction;
  targetId: string;
  seatId: string;
  expectedSeatRevision: number;
}

export interface Transition {
  state: RoomState;
  effect: ApplyModerationEffect;
}

export function canPublishAudio(
  state: RoomState,
  participantId: string
): boolean {
  if (state.phase !== "open") return false;

  return Object.values(state.seats).some(
    (seat) =>
      seat.occupantId === participantId &&
      seat.muted === false
  );
}

export function approveProposal(
  current: RoomState,
  proposalId: string,
  reviewerId: string,
  operationId: string,
  now: number
): Transition {
  const state = structuredClone(current);
  const proposal = state.proposals[proposalId];
  const reviewer = state.participants[reviewerId];

  if (!proposal) throw new Error("proposal_not_found");
  if (!reviewer) throw new Error("reviewer_not_found");
  if (state.phase !== "open") throw new Error("room_not_open");
  if (proposal.status !== "pending") throw new Error("proposal_not_pending");
  if (now >= proposal.expiresAt) throw new Error("proposal_expired");

  // An AI participant can recommend, but cannot commit an action.
  if (reviewer.kind !== "human") throw new Error("human_review_required");

  if (reviewer.role !== "host" && reviewer.role !== "moderator") {
    throw new Error("reviewer_not_authorized");
  }

  const seat = state.seats[proposal.expectedSeatId];
  if (!seat) throw new Error("seat_not_found");
  if (seat.occupantId !== proposal.targetId) {
    throw new Error("target_no_longer_on_expected_seat");
  }
  if (seat.revision !== proposal.expectedSeatRevision) {
    throw new Error("stale_seat_revision");
  }

  proposal.status = "applying";
  proposal.operationId = operationId;
  proposal.reviewedBy = reviewerId;

  return {
    state,
    effect: {
      type: "APPLY_MODERATION",
      operationId,
      proposalId,
      action: proposal.action,
      targetId: proposal.targetId,
      seatId: proposal.expectedSeatId,
      expectedSeatRevision: proposal.expectedSeatRevision
    }
  };
}

export type ApplyResult = "accepted" | "rejected" | "unknown";

export function recordApplyResult(
  current: RoomState,
  proposalId: string,
  operationId: string,
  result: ApplyResult
): RoomState {
  const state = structuredClone(current);
  const proposal = state.proposals[proposalId];

  if (!proposal) throw new Error("proposal_not_found");
  if (proposal.status !== "applying") throw new Error("proposal_not_applying");
  if (proposal.operationId !== operationId) throw new Error("stale_operation");

  if (result === "accepted") {
    // An accepted request is not yet proof that observed room state changed.
    proposal.status = "awaitingObservation";
  } else if (result === "rejected") {
    proposal.status = "failed";
    proposal.failureReason = "adapter_rejected_action";
  } else {
    proposal.status = "uncertain";
    proposal.failureReason = "action_result_unknown";
  }

  return state;
}

export function verifyObservedState(
  current: RoomState,
  proposalId: string,
  observedSeat: Seat
): RoomState {
  const state = structuredClone(current);
  const proposal = state.proposals[proposalId];

  if (!proposal) throw new Error("proposal_not_found");
  if (proposal.status !== "awaitingObservation") {
    throw new Error("proposal_not_awaiting_observation");
  }

  const conditionMet =
    proposal.action === "mute"
      ? observedSeat.occupantId === proposal.targetId && observedSeat.muted
      : observedSeat.occupantId !== proposal.targetId;

  if (conditionMet) {
    proposal.status = "verified";
  }

  state.seats[observedSeat.id] = observedSeat;
  return state;
}

There are three deliberate constraints in this model.

First, kind and role are separate. Labeling an AI participant as a moderator does not make it human or grant approval authority.

Second, a proposal refers to a specific seat revision. A recommendation about seat 2 should not be applied after seat 2 has been vacated and occupied by someone else.

Third, an accepted adapter request is not displayed as a completed action. Completion requires an observed seat state that matches the requested result.

Turn moderation scenarios into executable benchmarks

A generic “moderation accuracy” score will not reveal authority or race-condition failures. Build cases from situations your room must survive.

Create src/moderation.test.ts:

import { describe, expect, it } from "vitest";
import {
  approveProposal,
  canPublishAudio,
  recordApplyResult,
  verifyObservedState,
  type RoomState
} from "./moderation";

function room(): RoomState {
  return {
    phase: "open",
    participants: {
      host: { id: "host", kind: "human", role: "host" },
      speaker: { id: "speaker", kind: "human", role: "member" },
      bot: { id: "bot", kind: "ai", role: "moderator" }
    },
    seats: {
      s1: { id: "s1", occupantId: "speaker", muted: false, revision: 7 },
      s2: { id: "s2", occupantId: null, muted: false, revision: 3 }
    },
    proposals: {
      p1: {
        id: "p1",
        sourceId: "bot",
        targetId: "speaker",
        action: "mute",
        reason: "Possible repeated interruption",
        evidenceRefs: ["transcript-window-42"],
        expectedSeatId: "s1",
        expectedSeatRevision: 7,
        expiresAt: 20_000,
        status: "pending"
      }
    }
  };
}

describe("voice-room moderation protocol", () => {
  it("does not let an AI approve its own proposal", () => {
    expect(() =>
      approveProposal(room(), "p1", "bot", "op-1", 10_000)
    ).toThrow("human_review_required");
  });

  it("does not let an off-seat AI participant publish audio", () => {
    expect(canPublishAudio(room(), "bot")).toBe(false);
  });

  it("uses the same seat rule when the AI is allowed to speak", () => {
    const state = room();
    state.seats.s2 = {
      id: "s2",
      occupantId: "bot",
      muted: false,
      revision: 4
    };

    expect(canPublishAudio(state, "bot")).toBe(true);
  });

  it("rejects approval when the seat changed after the proposal", () => {
    const state = room();
    state.seats.s1 = {
      id: "s1",
      occupantId: "speaker",
      muted: false,
      revision: 8
    };

    expect(() =>
      approveProposal(state, "p1", "host", "op-2", 10_000)
    ).toThrow("stale_seat_revision");
  });

  it("waits for observed seat state before claiming success", () => {
    const approved = approveProposal(
      room(),
      "p1",
      "host",
      "op-3",
      10_000
    );

    expect(approved.state.proposals.p1.status).toBe("applying");

    const accepted = recordApplyResult(
      approved.state,
      "p1",
      "op-3",
      "accepted"
    );

    expect(accepted.proposals.p1.status).toBe("awaitingObservation");

    const verified = verifyObservedState(accepted, "p1", {
      id: "s1",
      occupantId: "speaker",
      muted: true,
      revision: 8
    });

    expect(verified.proposals.p1.status).toBe("verified");
  });

  it("shows an ambiguous timeout instead of pretending success", () => {
    const approved = approveProposal(
      room(),
      "p1",
      "host",
      "op-4",
      10_000
    );

    const uncertain = recordApplyResult(
      approved.state,
      "p1",
      "op-4",
      "unknown"
    );

    expect(uncertain.proposals.p1.status).toBe("uncertain");
    expect(uncertain.proposals.p1.failureReason).toBe(
      "action_result_unknown"
    );
  });
});

Run the benchmark:

npm test

These tests demonstrate the control protocol, not the quality of any particular model. A model’s moderation accuracy remains an empirical question that you must evaluate with representative, consented data and a written room policy.

Connect the controller to a Tencent RTC Voice Chat Room

The official implementation guide uses LiveListStore for room lifecycle and LiveSeatStore for mic-seat state. Keep those live concerns behind an adapter rather than importing SDK behavior into your policy functions.

Define the application boundary like this:

import type { ApplyModerationEffect, RoomPhase, Seat } from "./moderation";

export interface VoiceRoomAdapter {
  readRoomPhase(): Promise<RoomPhase>;
  readSeats(): Promise<Seat[]>;

  applyModeration(
    effect: ApplyModerationEffect
  ): Promise<"accepted" | "rejected" | "unknown">;
}

The concrete adapter in your application should:

Read the current room lifecycle from the room state connected to LiveListStore.
Convert the latest LiveSeatStore snapshot into the domain Seat representation.
Increment an application-owned revision whenever it accepts a changed seat snapshot.
Send the approved mute or remove request through the documented room integration used by your project.
Treat a timeout as unknown, not accepted or rejected.
Wait for a fresh seat observation before marking the proposal verified.

Do not let a client-provided role or an AI response directly invoke the adapter. Approval should be validated on a trusted application service using fresh room and seat state.

A practical event flow is:

seat snapshot
    ↓
application assigns seat revision
    ↓
AI or human submits recommendation
    ↓
moderation queue displays evidence and expiration
    ↓
human host/moderator approves
    ↓
server revalidates room, reviewer, occupant, and revision
    ↓
adapter requests the room action
    ↓
fresh seat snapshot verifies the resulting condition

The UI should display the actual states rather than collapsing them into a spinner:

Protocol state	Moderator-facing text
`pending`	Review requested
`applying`	Sending approved action
`awaitingObservation`	Action accepted; checking room state
`verified`	Room state verified
`failed`	Action rejected; review current seat state
`uncertain`	Result unknown; refresh before retrying
`dismissed`	No action taken

Where an AI moderator fits

An AI participant can be useful for narrowing a busy review queue, grouping similar reports, or pointing a human toward a short evidence window. None of those capabilities proves that it understands humor, reclaimed language, speaker relationships, or the room’s social context.

Keep the AI path explicit:

consented audio or text
    → speech recognition, if audio is used
    → bounded evidence window
    → model recommendation
    → pending proposal
    → human decision
    → server validation
    → RTC room action

Text-to-speech is a different path:

approved warning text
    → AI participant receives a mic seat
    → seat permission is verified
    → speech synthesis
    → audio publication

The model should not be able to produce a special response token that bypasses either path.

Also decide what evidence is retained. A reference such as transcript-window-42 is safer in domain state than copying raw audio or a full transcript into every moderation record, but the referenced data still needs access controls, retention rules, and user-visible consent appropriate to your service.

Build a benchmark from your policy, not from model confidence

Start with a small case matrix before evaluating any model:

Case	Expected recommendation	Required system behavior
Repeated interruption	Possibly review	Human decides; no automatic mute
Speaker leaves before review	Proposal becomes stale	Reject action against the old seat revision
New participant occupies the seat	No action on newcomer	Occupant and revision checks fail safely
AI requests to read a warning	Speech only after approval	AI needs an occupied, unmuted seat
Adapter times out	Unknown	Reconcile from fresh seat state before retry
Room begins closing	No new action	Approval fails because the room is not open
AI flags ambiguous humor	Review or dismiss	Preserve human contextual judgment

For each case, record three separate results:

Recommendation quality: Did the model produce a useful suggestion?
Protocol safety: Did the application prevent unauthorized or stale action?
Recovery clarity: Could the moderator understand what to do after failure?

This prevents a high classification score from hiding a dangerous control path.

Failure policies to decide before launch

The target leaves while the moderator is reading

The seat occupant or revision no longer matches. Reject the approval and label the proposal stale. Do not redirect the action to whoever occupies that seat next.

The AI recommends muting the host

Do not solve this with a prompt alone. Define protected-target policy in deterministic server code, or require an elevated review path appropriate to your room model.

The action request times out

A timeout does not reveal whether the remote operation happened. Mark the result uncertain, refresh authoritative seat state, and use an operation identifier or your persistence layer’s idempotency mechanism before allowing a retry.

The room closes during approval

Reject new approvals after the room leaves open. Closing and moderation should not race to create unexplained final actions.

The AI is on a seat when its warning is cancelled

Stop its speech path and remove or mute its speaking capability according to your room policy. Cancelling generated text is insufficient if synthesized audio is already queued.

Speech recognition or the model is unavailable

Keep human moderation usable. The queue should accept human reports and direct decisions without requiring the AI pipeline to recover first.

Release verification

Run the unit benchmark, then perform a live-room verification pass with non-production accounts:

[ ] A human member without moderation authority cannot approve a proposal.
[ ] An AI participant cannot approve a proposal, regardless of its role label.
[ ] An AI participant cannot publish audio while off-seat or muted.
[ ] A seat change invalidates recommendations created from an older revision.
[ ] An accepted action is not shown as verified until a fresh seat snapshot matches it.
[ ] An expired proposal cannot be approved from an old browser tab.
[ ] Closing the room prevents new moderation effects.
[ ] An adapter timeout produces an uncertain state and a reconciliation action.
[ ] The room remains moderatable when speech recognition or the model is unavailable.
[ ] Audit records distinguish the recommender, human reviewer, operation, and observed result.
[ ] Participants can understand when AI analysis or generated speech is in use.
[ ] Evidence access and retention follow the room’s consent and privacy policy.

The engineering skill that remains human

Adding AI does not reduce moderation engineering to choosing a model. The durable work is defining authority, identifying stale evidence, deciding which actions are reversible, and making uncertainty visible.

A model may help sort the queue. It cannot decide what your community promises its members or who is accountable when context is unclear. Encoding those decisions as executable cases gives both developers and moderators something more useful than a convincing demo: a system whose boundaries can be inspected and rerun.

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

Build Safer Link Previews for a Tencent RTC Community Chat

LunarDrift — Mon, 02 Nov 2026 17:11:49 +0000

A casual community prompt—share a pet photo, story, or favorite animal link—creates a surprisingly serious backend decision: should your chat server automatically fetch every URL that members post?

Automatic previews make a social space easier to browse. They also turn your infrastructure into an HTTP client controlled by untrusted input. A malicious or accidental URL could target a loopback address, a private service, an oversized document, or a public URL that redirects somewhere private.

The useful framing is not “Are link previews safe?” It is:

Which URLs may the preview worker fetch, what state should members see, and what happens when the worker cannot safely decide?

This tutorial builds that boundary in TypeScript. It is designed for a Tencent RTC Social Messaging community, but the security policy remains independent from the messaging SDK.

What we are building

A member posts this message:

This rescue organization has an adoption guide: https://example.org/adopt

The original message can appear immediately. Preview generation proceeds asynchronously through explicit states:

queued → validating → fetching → ready
                         ├──────→ blocked
                         └──────→ failed

Those terminal states mean different things:

ready: metadata was fetched within policy.
blocked: policy intentionally refused the URL, address, redirect, or content type.
failed: the operation was allowed but could not finish, such as a DNS or network failure.

A blocked or failed preview does not delete the member’s message. It also does not certify that the link itself is safe. It only describes the preview operation.

Tencent RTC’s Social Messaging solution covers community conversations and rich-media social experiences. We will use the messaging layer for conversation delivery while keeping URL fetching in an application-owned backend worker.

Create the reproducible project

Use Node.js with TypeScript:

mkdir community-link-preview
cd community-link-preview
npm init -y
npm install ipaddr.js
npm install --save-dev typescript tsx @types/node
mkdir src test

Update package.json:

{
  "type": "module",
  "scripts": {
    "test": "tsx --test test/*.test.ts",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "ipaddr.js": "^2.2.0"
  },
  "devDependencies": {
    "@types/node": "^24.0.0",
    "tsx": "^4.0.0",
    "typescript": "^5.0.0"
  }
}

Add tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src", "test"]
}

Exact dependency versions can be locked by your package manager. The ranges above are not Tencent RTC product requirements.

Implement the preview state machine

Create src/preview.ts:

import ipaddr from "ipaddr.js";

export type PreviewState =
  | "queued"
  | "validating"
  | "fetching"
  | "ready"
  | "blocked"
  | "failed";

export interface PreviewEvent {
  state: PreviewState;
  reason?: string;
  title?: string;
  finalUrl?: string;
}

export interface Resolver {
  resolve(hostname: string): Promise<string[]>;
}

export interface ResponseLike {
  status: number;
  location?: string;
  contentType?: string;
  body: string;
  bytes: number;
}

export interface Requester {
  get(url: URL): Promise<ResponseLike>;
}

export interface PreviewDependencies {
  resolver: Resolver;
  requester: Requester;
  maxBytes?: number;
  maxRedirects?: number;
}

class PolicyBlocked extends Error {}

function parseHttpUrl(raw: string): URL {
  let url: URL;

  try {
    url = new URL(raw);
  } catch {
    throw new PolicyBlocked("malformed_url");
  }

  if (url.protocol !== "http:" && url.protocol !== "https:") {
    throw new PolicyBlocked("unsupported_protocol");
  }

  if (url.username || url.password) {
    throw new PolicyBlocked("embedded_credentials");
  }

  if (!url.hostname) {
    throw new PolicyBlocked("missing_hostname");
  }

  return url;
}

function normalizedHostname(url: URL): string {
  // URL.hostname may retain brackets for an IPv6 literal.
  return url.hostname.replace(/^\[/, "").replace(/\]$/, "");
}

async function assertPublicDestination(
  url: URL,
  resolver: Resolver,
): Promise<void> {
  const hostname = normalizedHostname(url);
  let addresses: string[];

  try {
    addresses = ipaddr.isValid(hostname)
      ? [hostname]
      : await resolver.resolve(hostname);
  } catch {
    throw new Error("dns_resolution_failed");
  }

  if (addresses.length === 0) {
    throw new Error("dns_returned_no_addresses");
  }

  for (const address of addresses) {
    if (!ipaddr.isValid(address)) {
      throw new PolicyBlocked("resolver_returned_invalid_address");
    }

    const range = ipaddr.parse(address).range();

    // A conservative policy accepts only globally routable unicast results.
    // If DNS returns a mixture of public and private addresses, reject all.
    if (range !== "unicast") {
      throw new PolicyBlocked(`non_public_destination:${range}`);
    }
  }
}

function extractTitle(html: string): string | undefined {
  const match = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
  if (!match) return undefined;

  const title = match[1].replace(/\s+/g, " ").trim();
  return title ? title.slice(0, 200) : undefined;
}

export async function runPreview(
  rawUrl: string,
  dependencies: PreviewDependencies,
): Promise<PreviewEvent[]> {
  const events: PreviewEvent[] = [{ state: "queued" }];
  const maxBytes = dependencies.maxBytes ?? 256 * 1024;
  const maxRedirects = dependencies.maxRedirects ?? 3;

  const emit = (event: PreviewEvent) => events.push(event);

  let current: URL;

  try {
    emit({ state: "validating" });
    current = parseHttpUrl(rawUrl);
  } catch (error) {
    emit({
      state: "blocked",
      reason: error instanceof Error ? error.message : "invalid_url",
    });
    return events;
  }

  for (let redirectCount = 0; ; redirectCount += 1) {
    try {
      await assertPublicDestination(current, dependencies.resolver);
    } catch (error) {
      if (error instanceof PolicyBlocked) {
        emit({ state: "blocked", reason: error.message });
      } else {
        emit({
          state: "failed",
          reason: error instanceof Error ? error.message : "validation_failed",
        });
      }
      return events;
    }

    emit({ state: "fetching", finalUrl: current.toString() });

    let response: ResponseLike;
    try {
      response = await dependencies.requester.get(current);
    } catch {
      emit({ state: "failed", reason: "request_failed" });
      return events;
    }

    if (response.status >= 300 && response.status < 400) {
      if (!response.location) {
        emit({ state: "failed", reason: "redirect_without_location" });
        return events;
      }

      if (redirectCount >= maxRedirects) {
        emit({ state: "blocked", reason: "redirect_limit_exceeded" });
        return events;
      }

      try {
        // Relative redirects are resolved against the current URL.
        current = parseHttpUrl(new URL(response.location, current).toString());
      } catch (error) {
        emit({
          state: "blocked",
          reason: error instanceof Error ? error.message : "invalid_redirect",
        });
        return events;
      }

      // The next iteration resolves and validates the new destination.
      continue;
    }

    if (response.status !== 200) {
      emit({ state: "failed", reason: `http_status:${response.status}` });
      return events;
    }

    if (response.bytes > maxBytes) {
      emit({ state: "blocked", reason: "response_too_large" });
      return events;
    }

    const contentType = response.contentType?.toLowerCase() ?? "";
    if (!contentType.startsWith("text/html")) {
      emit({ state: "blocked", reason: "content_not_previewable" });
      return events;
    }

    emit({
      state: "ready",
      title: extractTitle(response.body),
      finalUrl: current.toString(),
    });
    return events;
  }
}

Two details matter here:

Every redirect is treated as a new untrusted destination.
If DNS returns even one private or otherwise non-public address, the job is blocked rather than selecting a more convenient result.

That second choice can reject some unusual but legitimate infrastructure. It is an intentional security-versus-compatibility trade-off.

Prove the dangerous paths without making network requests

Create test/preview.test.ts:

import assert from "node:assert/strict";
import test from "node:test";
import {
  runPreview,
  type Requester,
  type Resolver,
} from "../src/preview.js";

const publicResolver: Resolver = {
  async resolve() {
    return ["93.184.216.34"];
  },
};

test("blocks a direct loopback destination before requesting it", async () => {
  let requests = 0;

  const requester: Requester = {
    async get() {
      requests += 1;
      throw new Error("must not be called");
    },
  };

  const events = await runPreview("http://127.0.0.1/admin", {
    resolver: publicResolver,
    requester,
  });

  assert.equal(events.at(-1)?.state, "blocked");
  assert.match(events.at(-1)?.reason ?? "", /non_public_destination/);
  assert.equal(requests, 0);
});

test("revalidates a redirect instead of trusting the first host", async () => {
  let requests = 0;

  const requester: Requester = {
    async get() {
      requests += 1;
      return {
        status: 302,
        location: "http://127.0.0.1/internal",
        body: "",
        bytes: 0,
      };
    },
  };

  const events = await runPreview("https://public.example/start", {
    resolver: publicResolver,
    requester,
  });

  assert.equal(requests, 1);
  assert.equal(events.at(-1)?.state, "blocked");
});

test("returns a ready preview for allowed HTML", async () => {
  const requester: Requester = {
    async get() {
      const body = "<html><title>Pet Adoption Guide</title></html>";
      return {
        status: 200,
        contentType: "text/html; charset=utf-8",
        body,
        bytes: Buffer.byteLength(body),
      };
    },
  };

  const events = await runPreview("https://public.example/adopt", {
    resolver: publicResolver,
    requester,
  });

  assert.deepEqual(events.at(-1), {
    state: "ready",
    title: "Pet Adoption Guide",
    finalUrl: "https://public.example/adopt",
  });
});

test("blocks an oversized response", async () => {
  const requester: Requester = {
    async get() {
      return {
        status: 200,
        contentType: "text/html",
        body: "truncated",
        bytes: 300_000,
      };
    },
  };

  const events = await runPreview("https://public.example/large", {
    resolver: publicResolver,
    requester,
    maxBytes: 100_000,
  });

  assert.equal(events.at(-1)?.state, "blocked");
  assert.equal(events.at(-1)?.reason, "response_too_large");
});

Run the suite:

npm test
npm run typecheck

The tests verify policy without contacting a real site or depending on mutable public DNS.

The requester must stop reading at the byte limit

The test interface reports bytes, but a production requester must not download an unlimited response and check its size afterward. Enforce the limit while streaming.

A Node adapter can follow this shape:

import type { Requester, ResponseLike } from "./preview.js";

export class NodeRequester implements Requester {
  constructor(
    private readonly maxBytes = 256 * 1024,
    private readonly timeoutMs = 3_000,
  ) {}

  async get(url: URL): Promise<ResponseLike> {
    const response = await fetch(url, {
      redirect: "manual",
      signal: AbortSignal.timeout(this.timeoutMs),
      headers: {
        "user-agent": "CommunityPreviewBot/1.0",
        accept: "text/html",
      },
    });

    const location = response.headers.get("location") ?? undefined;
    const contentType = response.headers.get("content-type") ?? undefined;

    if (!response.body) {
      return {
        status: response.status,
        location,
        contentType,
        body: "",
        bytes: 0,
      };
    }

    const reader = response.body.getReader();
    const chunks: Uint8Array[] = [];
    let bytes = 0;

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      bytes += value.byteLength;
      if (bytes > this.maxBytes) {
        await reader.cancel();
        return {
          status: response.status,
          location,
          contentType,
          body: "",
          bytes,
        };
      }

      chunks.push(value);
    }

    const body = Buffer.concat(chunks).toString("utf8");
    return {
      status: response.status,
      location,
      contentType,
      body,
      bytes,
    };
  }
}

Do not render the extracted title with innerHTML. Treat it as untrusted text and let the UI framework escape it.

Important: DNS validation alone is not complete SSRF protection

There is a gap between resolving a hostname during validation and the HTTP client resolving it again during connection. An attacker may try to change the DNS answer between those operations.

For production, run the worker in a constrained network environment with egress rules that reject loopback, link-local, private, and internal destinations at the network layer. A controlled outbound proxy is another option. Connecting directly to a previously validated IP requires careful handling of TLS certificate validation and the original hostname; do not disable certificate checks to make it work.

The application policy and the network boundary should reinforce each other.

Connect the worker to Social Messaging

Keep the integration seam small. Your application needs to react to a delivered text message, enqueue URLs, and publish preview state back to clients through your own backend data channel or application storage.

interface CommunityTextMessage {
  applicationMessageId: string;
  conversationId: string;
  authorId: string;
  originalText: string;
}

interface PreviewRepository {
  createQueued(input: {
    previewId: string;
    messageId: string;
    url: string;
  }): Promise<boolean>; // false means the idempotency key already exists

  appendState(
    previewId: string,
    event: {
      state: string;
      reason?: string;
      title?: string;
      finalUrl?: string;
    },
  ): Promise<void>;
}

A practical workflow is:

Deliver the member’s original message through the Tencent RTC Social Messaging integration.
Give the message a stable application-level ID.
Extract only explicit http: and https: URLs from the original text.
Create one preview job per URL using messageId + normalized URL as an idempotency key.
Run preview work on the backend, never in another member’s browser.
Persist each visible transition.
Let clients subscribe to or poll your application’s preview records.
If a message is withdrawn or moderated, stop exposing its preview even if a worker finishes later.

The SDK adapter should translate documented message events into CommunityTextMessage. This tutorial deliberately does not invent a Tencent RTC method name: use the event and send interfaces documented for the SDK and platform version selected by your application.

For concurrent workers, make state updates conditional. For example, only let a worker write ready if the stored record is still fetching and its job generation matches. That prevents a delayed worker from restoring a preview after the associated message has been removed.

Do not generate previews from translated text

TUIChat provides on-demand text-message translation, subject to its documented content-type, language, and edition constraints. See the official TUIChat message translation documentation before enabling it.

Translation should be a reading aid, not a new source of executable URLs. Always discover preview candidates from the immutable original message—not translated output. Otherwise, a transformed URL or newly URL-shaped phrase could trigger a request the author never posted.

A useful data boundary is:

interface MessagePresentation {
  originalText: string;       // authoritative input for link discovery
  translatedText?: string;    // optional presentation only
  translationTarget?: string;
}

The translation result may be displayed near a preview, but it should not modify the preview job’s URL or authority.

Failure behavior members can understand

Avoid exposing infrastructure details such as resolved IP addresses or internal exception messages. Map internal reasons to a small set of user-facing outcomes:

Internal outcome	Member-facing behavior	Retry policy
`malformed_url`	No preview available	Do not retry
`non_public_destination:*`	Preview blocked by link policy	Do not retry automatically
`redirect_limit_exceeded`	Preview unavailable after too many redirects	Do not retry automatically
`response_too_large`	Page is too large to preview	Do not retry automatically
`content_not_previewable`	This content type has no preview	Do not retry
`dns_resolution_failed`	Preview could not be loaded	Retry with a strict limit
`request_failed`	Preview temporarily unavailable	Retry with backoff
`http_status:429`	Preview temporarily unavailable	Retry later; avoid a tight loop
Message removed during fetch	Hide preview and reject stale completion	Do not restore it

A retry should reuse the same preview record rather than creating duplicate cards. Store an attempt count and a next-attempt timestamp, and cap automatic retries.

Release verification checklist

Before enabling previews in a community, verify all of these with controlled tests:

[ ] Loopback IPv4 and IPv6 destinations are blocked.
[ ] Private, link-local, and non-unicast destinations are blocked.
[ ] Every redirect target is independently parsed and resolved.
[ ] Redirect depth is bounded.
[ ] DNS failure is distinguishable from a policy block.
[ ] Connection and body-read timeouts are enforced.
[ ] The response stream is cancelled when the byte limit is crossed.
[ ] Only approved content types are parsed.
[ ] Extracted titles are rendered as escaped text.
[ ] Preview workers have restricted network egress.
[ ] Duplicate message events do not create duplicate jobs.
[ ] Removing a message prevents a late worker from restoring its preview.
[ ] Translated text cannot create or modify preview requests.
[ ] A missing preview never causes the original community message to disappear.
[ ] Logs retain operational reasons without revealing them to ordinary members.

The practical decision

A lively community does not need to choose between plain links and an unrestricted crawler. The safer middle ground is a narrowly scoped preview service with explicit policy, bounded resource use, application-owned state, and a network boundary that assumes URLs are hostile.

For a small community, disabling automatic previews may still be the correct decision. If previews materially improve browsing, build them as a security-sensitive backend feature—not as a decorative client component.

What other user-supplied metadata does your community fetch automatically today: avatars, embeds, remote images, or attachment thumbnails?

Relationship disclosure: I am connected with Tencent RTC, and I used official Tencent RTC documentation as the implementation reference for the product integration described here.

Race-Proof On-Demand Translation in Tencent RTC TUIChat

LunarDrift — Fri, 30 Oct 2026 17:15:15 +0000

A member opens a message, requests a French translation, changes the target to German, and then sees the French result appear under the German label.

Nothing “random” happened. Two valid asynchronous operations completed in a different order from the one in which they started.

This is the same category of confusion behind JavaScript expressions such as {} + []: the runtime followed its rules, but those rules were not the contract the developer thought they had created.

For multilingual social messaging, the fix is not another loading spinner. We need to make the message identity, source text, target language, request generation, and visible result explicit.

In this tutorial, we will build a framework-independent TypeScript controller for on-demand translation around a Tencent RTC TUIChat integration. It will:

keep results associated with the correct target language;
ignore stale completions without assuming requests can be canceled;
avoid JavaScript cache-key coercion;
distinguish unsupported configurations from network failures;
preserve the original message alongside its translation;
remain reproducible without inventing an undocumented SDK method.

Tencent RTC documents on-demand TUIChat message translation, including supported content types, languages, and edition requirements. Check those constraints before exposing the control in your application: TUIChat message translation.

The bug we are going to reproduce

Suppose the current message is:

In JavaScript, why does {} + [] sometimes produce 0?

A reader selects French and immediately switches to German:

Request A: message-42 → French
Request B: message-42 → German

If A finishes last and the component stores only one translatedText field, it can overwrite B:

// Too little state
let translatedText = "";
let selectedLanguage = "de";

async function translate(targetLanguage: string) {
  translatedText = await requestTranslation(targetLanguage);
}

The interface now says “German” while displaying French. The translation service did not necessarily fail; the application lost the relationship between request and result.

A second tempting mistake is to build cache keys through +:

const key = message.id + targetLanguage + message.text;

This relies on implicit string conversion and has no structural boundaries. Different tuples can produce the same string, while non-string values can be coerced in surprising ways.

We will instead treat a translation as a value identified by this tuple:

(message ID, exact source text, target language)

Create the testable project

Start with a minimal TypeScript project:

mkdir chat-translation-state
cd chat-translation-state
npm init -y
npm install --save-dev typescript tsx @types/node

Add a test script to package.json:

{
  "scripts": {
    "test": "tsx --test translation.test.ts"
  }
}

The controller will depend on an application-owned port rather than a guessed Tencent RTC API name:

export interface Translator {
  translate(input: {
    messageId: string;
    sourceText: string;
    targetLanguage: string;
  }): Promise<string>;
}

This boundary is deliberate. The reproducible state logic should not depend on a particular UI framework or fabricate a convenience method that may not exist in the TUIChat package you selected.

Model what the reader can actually see

Create translation.ts:

export interface ChatMessage {
  id: string;
  text: string;
}

export interface Translator {
  translate(input: {
    messageId: string;
    sourceText: string;
    targetLanguage: string;
  }): Promise<string>;
}

export interface TranslationPolicy {
  enabled: boolean;
  allowedTargetLanguages: ReadonlySet<string>;
}

export type TranslationView =
  | { status: "idle" }
  | {
      status: "unsupported";
      targetLanguage: string;
      reason: string;
    }
  | {
      status: "loading";
      targetLanguage: string;
      sourceText: string;
    }
  | {
      status: "ready";
      targetLanguage: string;
      sourceText: string;
      translatedText: string;
    }
  | {
      status: "failed";
      targetLanguage: string;
      sourceText: string;
      error: string;
    };

type Entry = Exclude<TranslationView, { status: "idle" }> & {
  requestId?: number;
};

type ActiveSelection = {
  key: string;
  message: ChatMessage;
  targetLanguage: string;
};

function translationKey(
  message: ChatMessage,
  targetLanguage: string,
): string {
  // A serialized tuple preserves boundaries and avoids `+` coercion.
  return JSON.stringify([message.id, message.text, targetLanguage]);
}

function errorMessage(error: unknown): string {
  return error instanceof Error ? error.message : "Translation failed";
}

export class TranslationController {
  private readonly entries = new Map<string, Entry>();
  private active?: ActiveSelection;
  private nextRequestId = 0;

  constructor(
    private readonly translator: Translator,
    private readonly policy: TranslationPolicy,
  ) {}

  get view(): TranslationView {
    if (!this.active) return { status: "idle" };
    return this.entries.get(this.active.key) ?? { status: "idle" };
  }

  select(message: ChatMessage, targetLanguage: string): void {
    const key = translationKey(message, targetLanguage);
    this.active = { key, message, targetLanguage };

    if (!this.policy.enabled) {
      this.entries.set(key, {
        status: "unsupported",
        targetLanguage,
        reason: "Translation is not enabled for this deployment.",
      });
      return;
    }

    if (!this.policy.allowedTargetLanguages.has(targetLanguage)) {
      this.entries.set(key, {
        status: "unsupported",
        targetLanguage,
        reason: "This target language is not configured as supported.",
      });
      return;
    }

    const existing = this.entries.get(key);

    // Reuse a completed result and deduplicate an in-flight request.
    if (existing?.status === "ready" || existing?.status === "loading") {
      return;
    }

    const requestId = ++this.nextRequestId;

    this.entries.set(key, {
      status: "loading",
      requestId,
      targetLanguage,
      sourceText: message.text,
    });

    void this.translator
      .translate({
        messageId: message.id,
        sourceText: message.text,
        targetLanguage,
      })
      .then((translatedText) => {
        const current = this.entries.get(key);

        // A retry may have replaced this request for the same key.
        if (
          current?.status !== "loading" ||
          current.requestId !== requestId
        ) {
          return;
        }

        this.entries.set(key, {
          status: "ready",
          targetLanguage,
          sourceText: message.text,
          translatedText,
        });
      })
      .catch((error: unknown) => {
        const current = this.entries.get(key);

        if (
          current?.status !== "loading" ||
          current.requestId !== requestId
        ) {
          return;
        }

        this.entries.set(key, {
          status: "failed",
          targetLanguage,
          sourceText: message.text,
          error: errorMessage(error),
        });
      });
  }

  retry(): void {
    if (!this.active) return;

    const { key, message, targetLanguage } = this.active;
    this.entries.delete(key);
    this.select(message, targetLanguage);
  }

  dismiss(): void {
    this.active = undefined;
  }
}

There are two useful stale-result protections here.

First, the visible view is selected by a structured key. A French completion can update the French cache entry, but it cannot become the active German view.

Second, every request has a generation number. If a failed request is retried for the same key, the earlier completion cannot overwrite the retry.

We do not require cancellation for correctness. An adapter may cancel network work if its documented interface supports that, but stale-result rejection remains necessary because cancellation itself can race with completion.

Prove the out-of-order case

Create translation.test.ts:

import assert from "node:assert/strict";
import test from "node:test";
import {
  TranslationController,
  type Translator,
} from "./translation.js";

function deferred<T>() {
  let resolve!: (value: T) => void;
  let reject!: (reason?: unknown) => void;

  const promise = new Promise<T>((res, rej) => {
    resolve = res;
    reject = rej;
  });

  return { promise, resolve, reject };
}

const tick = () => new Promise<void>((resolve) => setImmediate(resolve));

test("a stale language result never replaces the active language", async () => {
  const french = deferred<string>();
  const german = deferred<string>();

  const translator: Translator = {
    translate: ({ targetLanguage }) => {
      if (targetLanguage === "fr") return french.promise;
      if (targetLanguage === "de") return german.promise;
      throw new Error("Unexpected language");
    },
  };

  const controller = new TranslationController(translator, {
    enabled: true,
    allowedTargetLanguages: new Set(["fr", "de"]),
  });

  const message = {
    id: "message-42",
    text: "Why does {} + [] sometimes produce 0?",
  };

  controller.select(message, "fr");
  controller.select(message, "de");

  french.resolve("French result");
  await tick();

  assert.deepEqual(controller.view, {
    status: "loading",
    targetLanguage: "de",
    sourceText: message.text,
  });

  german.resolve("German result");
  await tick();

  assert.deepEqual(controller.view, {
    status: "ready",
    targetLanguage: "de",
    sourceText: message.text,
    translatedText: "German result",
  });
});

test("unsupported languages do not start a request", () => {
  let calls = 0;

  const translator: Translator = {
    async translate() {
      calls += 1;
      return "unused";
    },
  };

  const controller = new TranslationController(translator, {
    enabled: true,
    allowedTargetLanguages: new Set(["fr"]),
  });

  controller.select({ id: "m1", text: "Hello" }, "xx");

  assert.equal(controller.view.status, "unsupported");
  assert.equal(calls, 0);
});

test("a failed translation can be retried explicitly", async () => {
  let calls = 0;

  const translator: Translator = {
    async translate() {
      calls += 1;
      if (calls === 1) throw new Error("Temporary failure");
      return "Bonjour";
    },
  };

  const controller = new TranslationController(translator, {
    enabled: true,
    allowedTargetLanguages: new Set(["fr"]),
  });

  controller.select({ id: "m2", text: "Hello" }, "fr");
  await tick();

  assert.equal(controller.view.status, "failed");

  controller.retry();
  await tick();

  assert.deepEqual(controller.view, {
    status: "ready",
    targetLanguage: "fr",
    sourceText: "Hello",
    translatedText: "Bonjour",
  });
});

Run the suite:

npm test

These tests do not prove translation quality. They prove something narrower and essential: the application will not knowingly display a valid result under the wrong request context.

Connect the controller to TUIChat without guessing APIs

Tencent RTC’s Social Messaging solution includes 1-to-1 chat, group discussions, communities, rich media, and live-room messaging. That makes translation a reading feature within a broader messaging experience, not a replacement for the original message. See the Social Messaging solution.

Use this production workflow:

Confirm product eligibility. Check the official translation documentation for the supported message content types, target languages, and edition requirements.
Configure TUIChat using the documented steps for your selected package. Do not copy an API name from a different platform or package version.
Populate allowedTargetLanguages from deployment configuration. Do not hardcode a language merely because an external translation service recognizes it.
Connect the documented translation operation to the Translator port. Keep Tencent-specific integration code inside that adapter.
Render the controller state in your application-owned language picker or translation panel. If your chosen TUIChat component owns the entire translation interface and exposes no extension point, use its documented behavior rather than attempting to patch internal component state.

The adapter shape should remain small:

import type { Translator } from "./translation.js";

export function createTranslator(
  documentedTranslationBridge: Translator["translate"],
): Translator {
  return {
    translate: documentedTranslationBridge,
  };
}

documentedTranslationBridge is intentionally not implemented here. Replace it with the exact integration described for your TUIChat package in the official documentation. This avoids presenting a made-up SDK method as working code.

Decide which messages should offer translation

A translate button on every object in a timeline is not automatically helpful. Use a content policy before making the action visible.

Message shape	Suggested behavior	Reason
Plain prose	Offer on-demand translation	This is the clearest use case
Prose with inline code	Offer translation, retain the source beside it	Identifiers and operators carry technical meaning
Code-only block	Keep the original prominent; consider omitting translation	Rewriting syntax can make valid code invalid
Attachment or rich media	Follow the exact supported-content table	Do not imply unsupported content was translated
Unknown target language	Show `unsupported`; do not send a request	A deterministic configuration issue is not a retryable outage

The JavaScript example demonstrates why this matters. In a developer community, braces, brackets, and operators may be syntax rather than punctuation. Translation can help with the surrounding explanation, but the original code must remain available for comparison.

Do not silently replace the source message. A useful rendering is:

Original
In JavaScript, why does {} + [] sometimes produce 0?

Translated to German
…

Also render translated output as text, not injected HTML. In the DOM, prefer textContent; React’s normal text interpolation also escapes content. A translated string is display data, not trusted markup.

Failure behavior should name the next action

Different failures deserve different interfaces:

Translation is unavailable for the deployment

Show that translation is unavailable. Do not display a retry button that can never succeed.

The target language is unsupported

Keep the original visible and let the reader choose another configured language.

The request fails temporarily

Show the original message, retain the selected target, and offer an explicit retry. Avoid an unbounded automatic retry loop triggered by every render.

The reader switches languages during a request

Move the visible panel to the newly selected language immediately. An older completion may be cached under its own key, but it must not replace the active view.

The source text changes locally

Because the exact source text is part of the key, a result generated for the earlier text will not be shown for the new text. This is useful even if your normal message model is immutable: local reconciliation, moderation views, or application-specific updates can still replace displayed content.

The message disappears while translation is running

Call dismiss(). A late result may complete internally, but the controller remains idle and does not reopen the panel.

Verification before release

Run the unit tests, then verify the real integration with this checklist:

[ ] Translation is initiated only by a visible user action.
[ ] The original message remains readable while loading and after completion.
[ ] Rapidly switching between two target languages never mislabels a result.
[ ] Selecting the same language repeatedly does not create duplicate in-flight requests.
[ ] A retry cannot be overwritten by the request it replaced.
[ ] Unsupported languages produce no network request.
[ ] Deployment configuration matches the current official language, content-type, and edition documentation.
[ ] Code blocks and inline identifiers remain visible in their original form.
[ ] Translation errors do not hide or alter the source message.
[ ] Translated strings are rendered as text rather than trusted HTML.
[ ] Leaving the message or closing the panel prevents late completions from reopening it.
[ ] Telemetry distinguishes unsupported, failed, and stale completions instead of grouping everything under “translation error.”

The broader lesson is not that JavaScript or asynchronous messaging is broken. It is that implicit state creates misleading interfaces.

A translation result is not just a string. It is a string produced for a particular message body, target language, request generation, and deployment capability. Once those facts become part of the model, out-of-order completion becomes an ordinary case you can test—not a mysterious production bug.

What does your chat treat as the owner of the target language: the account, the conversation, or each individual translation request? That decision determines both your cache boundary and what users expect when they move between communities.

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

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.