An Avatar Failure Must Not Reveal the Camera: Build a Consent-Safe Beauty AR Fallback Governor

quality avatar → performance avatar → sticker → camera

mkdir avatar-fallback-governor
cd avatar-fallback-governor
npm init -y
npm install --save-dev typescript tsx @types/node
mkdir src test

{
  "scripts": {
    "demo": "tsx src/demo.ts",
    "test": "tsx --test test/**/*.test.ts",
    "typecheck": "tsc --noEmit"
  }
}

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

export type DeviceTier = "high" | "medium" | "low" | "unknown";

export type Profile =
  | "avatarQuality"
  | "avatarPerformance"
  | "sticker"
  | "camera"
  | "paused";

export interface Consent {
  avatarTracking: boolean;
  allowStickerFallback: boolean;
  allowCameraFallback: boolean;
}

export interface PolicyConfig {
  badWindowsBeforeDegrade: number;
  goodWindowsBeforeUpgrade: number;
}

export interface State {
  phase: "idle" | "applying" | "live" | "paused" | "error" | "stopped";
  ladder: readonly Profile[];
  active: Profile | null;
  target: Profile | null;
  badWindows: number;
  goodWindows: number;
  operationToken: number;
  lastError?: string;
}

export type Event =
  | { type: "START" }
  | { type: "SAMPLE"; overBudget: boolean }
  | { type: "APPLIED"; profile: Profile; token: number }
  | { type: "APPLY_FAILED"; profile: Profile; token: number; message: string }
  | { type: "CAMERA_INTERRUPTED"; message: string }
  | { type: "RETRY" }
  | { type: "STOP" };

export type Action = {
  type: "APPLY_PROFILE";
  profile: Profile;
  token: number;
};

export interface Transition {
  state: State;
  action?: Action;
}

export function buildLadder(
  tier: DeviceTier,
  consent: Consent,
): readonly Profile[] {
  if (!consent.avatarTracking) return ["paused"];

  const ladder: Profile[] = [];

  // Product-defined profiles, not Tencent RTC API or edition names.
  if (tier === "high") ladder.push("avatarQuality");
  ladder.push("avatarPerformance");

  if (consent.allowStickerFallback) ladder.push("sticker");
  if (consent.allowCameraFallback) ladder.push("camera");

  // There is always a fail-closed destination.
  ladder.push("paused");
  return ladder;
}

export function initialState(ladder: readonly Profile[]): State {
  return {
    phase: "idle",
    ladder,
    active: null,
    target: null,
    badWindows: 0,
    goodWindows: 0,
    operationToken: 0,
  };
}

function schedule(state: State, profile: Profile): Transition {
  const token = state.operationToken + 1;

  return {
    state: {
      ...state,
      phase: "applying",
      target: profile,
      operationToken: token,
      badWindows: 0,
      goodWindows: 0,
    },
    action: { type: "APPLY_PROFILE", profile, token },
  };
}

function indexOfActive(state: State): number {
  if (state.active === null) return -1;
  return state.ladder.indexOf(state.active);
}

export function reduce(
  state: State,
  event: Event,
  config: PolicyConfig,
): Transition {
  switch (event.type) {
    case "START":
    case "RETRY": {
      const first = state.ladder[0];
      if (!first) {
        return {
          state: { ...state, phase: "error", lastError: "Empty profile ladder" },
        };
      }
      return schedule(state, first);
    }

    case "APPLIED": {
      if (
        event.token !== state.operationToken ||
        event.profile !== state.target ||
        state.phase !== "applying"
      ) {
        return { state }; // stale completion
      }

      return {
        state: {
          ...state,
          phase: event.profile === "paused" ? "paused" : "live",
          active: event.profile,
          target: null,
          badWindows: 0,
          goodWindows: 0,
          lastError: undefined,
        },
      };
    }

    case "APPLY_FAILED": {
      if (
        event.token !== state.operationToken ||
        event.profile !== state.target
      ) {
        return { state };
      }

      const failedIndex = state.ladder.indexOf(event.profile);
      const fallback = state.ladder[failedIndex + 1];

      if (!fallback) {
        return {
          state: {
            ...state,
            phase: "error",
            active: null,
            target: null,
            lastError: event.message,
          },
        };
      }

      const next = schedule(
        { ...state, active: null, lastError: event.message },
        fallback,
      );
      return next;
    }

    case "SAMPLE": {
      if (state.phase !== "live" || state.active === null) {
        return { state };
      }

      const activeIndex = indexOfActive(state);

      if (event.overBudget) {
        const badWindows = state.badWindows + 1;

        if (badWindows < config.badWindowsBeforeDegrade) {
          return {
            state: { ...state, badWindows, goodWindows: 0 },
          };
        }

        const fallback = state.ladder[activeIndex + 1];
        return fallback
          ? schedule(state, fallback)
          : { state: { ...state, badWindows, goodWindows: 0 } };
      }

      const goodWindows = state.goodWindows + 1;

      // Recovery requires a longer stable period than degradation.
      if (
        activeIndex > 0 &&
        goodWindows >= config.goodWindowsBeforeUpgrade
      ) {
        const upgrade = state.ladder[activeIndex - 1];
        return upgrade ? schedule(state, upgrade) : { state };
      }

      return {
        state: { ...state, goodWindows, badWindows: 0 },
      };
    }

    case "CAMERA_INTERRUPTED":
      return {
        state: {
          ...state,
          phase: "error",
          active: null,
          target: null,
          operationToken: state.operationToken + 1,
          lastError: event.message,
        },
      };

    case "STOP":
      return {
        state: {
          ...state,
          phase: "stopped",
          active: null,
          target: null,
          operationToken: state.operationToken + 1,
          badWindows: 0,
          goodWindows: 0,
        },
      };
  }
}

import {
  buildLadder,
  initialState,
  reduce,
  type Action,
  type PolicyConfig,
  type Profile,
  type State,
} from "./governor.js";

interface BeautyAdapter {
  apply(profile: Profile): Promise<void>;
  hardStop(): Promise<void>;
}

const adapter: BeautyAdapter = {
  async apply(profile) {
    // Replace this switch with documented SDK calls for your target platform.
    console.log("Applying:", profile);

    switch (profile) {
      case "avatarQuality":
        // Configure the selected avatar and your quality-oriented settings.
        break;
      case "avatarPerformance":
        // Select performance-oriented settings. Reduce optional workload,
        // resolution, or frame rate according to measured device behavior.
        break;
      case "sticker":
        // Disable the avatar path before enabling an approved sticker.
        break;
      case "camera":
        // Publish an unmodified/approved camera presentation only if consented.
        break;
      case "paused":
        // Disable visual effects and stop visual publication/capture as required
        // by the product's privacy contract.
        break;
    }
  },

  async hardStop() {
    // Map this to your platform's local capture/publication shutdown path.
    console.log("Hard stop visual pipeline");
  },
};

const config: PolicyConfig = {
  badWindowsBeforeDegrade: 3,
  goodWindowsBeforeUpgrade: 8,
};

let state: State = initialState(
  buildLadder("low", {
    avatarTracking: true,
    allowStickerFallback: true,
    allowCameraFallback: false,
  }),
);

async function execute(action?: Action): Promise<void> {
  if (!action) return;

  try {
    await adapter.apply(action.profile);
    dispatch({
      type: "APPLIED",
      profile: action.profile,
      token: action.token,
    });
  } catch (error) {
    if (action.profile === "paused") {
      await adapter.hardStop();
    }

    dispatch({
      type: "APPLY_FAILED",
      profile: action.profile,
      token: action.token,
      message: error instanceof Error ? error.message : "Unknown apply failure",
    });
  }
}

function dispatch(event: Parameters<typeof reduce>[1]): void {
  const result = reduce(state, event, config);
  state = result.state;
  console.log(event.type, "=>", state.phase, state.active ?? state.target);
  void execute(result.action);
}

dispatch({ type: "START" });

npm run demo

interface PerformanceWindow {
  startedAt: number;
  endedAt: number;
  processedFrames: number;
  lateFrames: number;
  effectErrors: number;
  thermalPressure?: "normal" | "elevated" | "critical";
  overBudget: boolean;
  reason: string;
}

import test from "node:test";
import assert from "node:assert/strict";
import {
  buildLadder,
  initialState,
  reduce,
  type PolicyConfig,
  type State,
} from "../src/governor.js";

const config: PolicyConfig = {
  badWindowsBeforeDegrade: 3,
  goodWindowsBeforeUpgrade: 8,
};

function step(state: State, event: Parameters<typeof reduce>[1]) {
  return reduce(state, event, config);
}

test("camera is absent when camera fallback was not approved", () => {
  const ladder = buildLadder("low", {
    avatarTracking: true,
    allowStickerFallback: false,
    allowCameraFallback: false,
  });

  assert.deepEqual(ladder, ["avatarPerformance", "paused"]);
});

test("three bad windows degrade to paused, never camera", () => {
  let state = initialState(
    buildLadder("low", {
      avatarTracking: true,
      allowStickerFallback: false,
      allowCameraFallback: false,
    }),
  );

  let result = step(state, { type: "START" });
  state = result.state;
  const start = result.action!;

  result = step(state, {
    type: "APPLIED",
    profile: start.profile,
    token: start.token,
  });
  state = result.state;

  state = step(state, { type: "SAMPLE", overBudget: true }).state;
  state = step(state, { type: "SAMPLE", overBudget: true }).state;
  result = step(state, { type: "SAMPLE", overBudget: true });

  assert.equal(result.action?.profile, "paused");
  assert.notEqual(result.action?.profile, "camera");
});

test("a stale profile completion cannot revive a stopped session", () => {
  let state = initialState(
    buildLadder("high", {
      avatarTracking: true,
      allowStickerFallback: true,
      allowCameraFallback: false,
    }),
  );

  const starting = step(state, { type: "START" });
  state = starting.state;
  const oldAction = starting.action!;

  state = step(state, { type: "STOP" }).state;
  state = step(state, {
    type: "APPLIED",
    profile: oldAction.profile,
    token: oldAction.token,
  }).state;

  assert.equal(state.phase, "stopped");
  assert.equal(state.active, null);
});

test("recovery requires a sustained stable period", () => {
  let state = initialState(["avatarQuality", "avatarPerformance", "paused"]);

  let result = step(state, { type: "START" });
  state = result.state;
  state = step(state, {
    type: "APPLIED",
    profile: "avatarQuality",
    token: result.action!.token,
  }).state;

  for (let i = 0; i < 3; i++) {
    result = step(state, { type: "SAMPLE", overBudget: true });
    state = result.state;
  }

  state = step(state, {
    type: "APPLIED",
    profile: "avatarPerformance",
    token: result.action!.token,
  }).state;

  for (let i = 0; i < 7; i++) {
    result = step(state, { type: "SAMPLE", overBudget: false });
    state = result.state;
    assert.equal(result.action, undefined);
  }

  result = step(state, { type: "SAMPLE", overBudget: false });
  assert.equal(result.action?.profile, "avatarQuality");
});

npm test
npm run typecheck