@volter/twin-livekit 0.1.0

package/src/livekit-conformance.ts

@@ -0,0 +1,15 @@
+import { handleLiveKitTwinRequest } from './livekit-twin.ts';
+
+export type LiveKitConformanceReport = { ok: boolean; checksRun: number; failures: string[] };
+
+export async function checkLiveKitConformance(options: { root?: string } = {}): Promise<LiveKitConformanceReport> {
+  const failures: string[] = [];
+  const check = async (name: string, ok: boolean) => { if (!ok) failures.push(name); };
+  const create = await handleLiveKitTwinRequest({ method: 'POST', path: '/twirp/livekit.RoomService/CreateRoom', body: JSON.stringify({ name: 'test-conformance', emptyTimeout: 600 }), root: options.root });
+  await check('create room returns room name', create.status === 200 && (create.body as any).name === 'test-conformance');
+  const list = await handleLiveKitTwinRequest({ method: 'POST', path: '/twirp/livekit.RoomService/ListRooms', body: JSON.stringify({ names: ['test-conformance'] }), root: options.root });
+  await check('list rooms returns created room', list.status === 200 && (list.body as any).rooms?.[0]?.name === 'test-conformance');
+  const bad = await handleLiveKitTwinRequest({ method: 'POST', path: '/twirp/livekit.RoomService/CreateRoom', body: JSON.stringify({}), root: options.root });
+  await check('missing room name rejects', bad.status === 400 && (bad.body as any).code === 'invalid_argument');
+  return { ok: failures.length === 0, checksRun: 3, failures };
+}

package/src/livekit-connector.ts

@@ -0,0 +1,406 @@
+// LiveKit CONNECTOR — pull/push against an INJECTED `LiveKitExecute`, so every test and every
+// capability verify runs offline against a deterministic fake. `liveLiveKitExecute` below is the pack's
+// single construction site for a REAL one, with the fail-closed rate budget inside it.
+import { observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { LiveKitBudget, LiveKitBudgetError, liveKitCallWeight, type LiveKitBudgetOptions } from './livekit-budget.ts';
+import { EGRESS_STATUS, SERVICE, defaultParticipant, egressResourceId, ingressResourceId, roomId } from './livekit-data.ts';
+import { mintAccessToken, type LiveKitVideoGrant } from './livekit-token.ts';
+import type {
+  LiveKitAgentDispatch,
+  LiveKitEgress,
+  LiveKitIngress,
+  LiveKitParticipant,
+  LiveKitRoom,
+  LiveKitSIPDispatchRule,
+  LiveKitSIPInboundTrunk,
+  LiveKitSIPOutboundTrunk,
+} from './livekit-types.ts';
+
+export type LiveKitService = 'RoomService' | 'Egress' | 'Ingress' | 'SIP' | 'AgentDispatchService';
+export type LiveKitExecute = (req: { service: LiveKitService; method: string; body?: unknown }) => Promise<{ status: number; data: unknown }>;
+
+const DEFAULT_OCCURRED_AT = '1970-01-01T00:00:00.000Z';
+
+// ── THE CHOKE POINT ─────────────────────────────────────────────────────────────────────────
+// `liveLiveKitExecute` is the pack's ONE construction site for a real, network-calling execute —
+// the choke point the rate budget sits inside. Before it existed there was nowhere for a guard to
+// live: the pack only ever received an execute, so a budget could only be something the caller
+// remembered to opt into, and "the caller remembered" is exactly the assumption that cost a ~4.5-day
+// Figma token lockout (2026-07-25). LiveKit's Server API limit is 1,000 requests/minute PER PROJECT
+// and this connector's snapshot fans out one request PER ROOM — see `livekit-budget.ts`.
+//
+// The injected contract is UNCHANGED: everything else in this file still takes a plain `LiveKitExecute`.
+
+/**
+ * The video grant each Twirp METHOD requires. A hand-mirror of the `GRANT_REQUIRED` table in
+ * `livekit-twin.ts` (which itself mirrors LiveKit's own auth middleware), kept here rather than
+ * imported so the connector does not pull the twin's request handler into its module graph —
+ * and BOUND to it by a test (`livekit-budget.test.ts`) that fails the moment the two disagree,
+ * so the copy cannot drift into a silent 403. (§9 finding, 2026-07-26.)
+ *
+ * PER-METHOD, not per-service: the token is minted per call anyway, so least privilege is free.
+ * A service-granularity union would have put `roomCreate` — the grant `RoomService.DeleteRoom`
+ * needs — on every `ListRooms` this connector issues, which is a strictly broader token than the
+ * call requires and than livekit-server-sdk would sign.
+ */
+export const LIVEKIT_METHOD_VIDEO_GRANT: Record<string, keyof LiveKitVideoGrant> = {
+  'RoomService.ListRooms': 'roomList',
+  'RoomService.ListParticipants': 'roomAdmin',
+  'RoomService.UpdateRoomMetadata': 'roomAdmin',
+  'Egress.ListEgress': 'roomRecord',
+  'Egress.StopEgress': 'roomRecord',
+  'Ingress.ListIngress': 'ingressAdmin',
+  'AgentDispatchService.ListDispatch': 'roomAdmin',
+};
+
+/**
+ * The fallback when a caller invokes a method the table above does not name: the UNION of the
+ * grants that service's methods need, which is what livekit-server-sdk's service clients sign.
+ * Broader than a per-method grant, deliberately — an unknown method must still be able to
+ * authorize — but never broader than its own service.
+ *
+ * SIP is the one service that authorizes off the SIP grant rather than a video grant; that is
+ * LiveKit's own scheme, recorded in `livekit-twin.ts`'s note on the same table.
+ */
+const SERVICE_GRANT_UNION: Record<LiveKitService, { video?: LiveKitVideoGrant; sip?: { admin: boolean } }> = {
+  RoomService: { video: { roomCreate: true, roomList: true, roomAdmin: true } },
+  Egress: { video: { roomRecord: true } },
+  Ingress: { video: { ingressAdmin: true } },
+  SIP: { sip: { admin: true } },
+  AgentDispatchService: { video: { roomAdmin: true } },
+};
+
+/** The least-privilege grant for one call: the per-method one when known, else the service union. */
+export function liveKitGrantFor(service: LiveKitService, method: string): { video?: LiveKitVideoGrant; sip?: { admin: boolean } } {
+  const only = LIVEKIT_METHOD_VIDEO_GRANT[`${service}.${method}`];
+  if (only) return { video: { [only]: true } as LiveKitVideoGrant };
+  return SERVICE_GRANT_UNION[service] ?? {};
+}
+
+/**
+ * The HTTP origin for a LiveKit Server API call. LiveKit hands out a `wss://`/`ws://` project URL
+ * (`LIVEKIT_URL`) because that is what the media SDKs want; the Server APIs live at the same host over
+ * HTTP(S), which is why every LiveKit server SDK performs exactly this scheme swap. An `http(s)://`
+ * URL is passed through unchanged (a self-hosted deployment is usually configured that way).
+ */
+export function liveKitHttpOrigin(url: string): string {
+  const trimmed = url.trim().replace(/\/+$/, '');
+  if (/^wss:\/\//i.test(trimmed)) return `https://${trimmed.slice(6)}`;
+  if (/^ws:\/\//i.test(trimmed)) return `http://${trimmed.slice(5)}`;
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  throw new Error(`LIVEKIT_URL must be a ws://, wss://, http:// or https:// URL (got ${url || '<empty>'})`);
+}
+
+/**
+ * The Twirp path for one RPC. LiveKit's server routes every Server API call under this shape.
+ *
+ * The method name is VALIDATED, not merely interpolated: it arrives from the caller, and a value
+ * containing `/`, `..` or a query string would reshape the URL this factory then sends a credentialed
+ * request to. A Twirp method is a protobuf RPC name, so the identifier grammar is exact, not a guess.
+ * (§9 hardening, 2026-07-26.)
+ */
+export function liveKitTwirpPath(service: LiveKitService, method: string): string {
+  if (typeof method !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*$/.test(method)) {
+    throw new Error(`liveKitTwirpPath: "${String(method)}" is not a Twirp method name — refusing to build a request URL from it`);
+  }
+  return `/twirp/livekit.${service}/${method}`;
+}
+
+/**
+ * THE CHOKE POINT — the one place this pack builds a `LiveKitExecute` that really reaches a LiveKit
+ * server, and therefore the one place the rate budget has to be enforced.
+ *
+ * Reads `LIVEKIT_URL`, `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` from the environment (the same three
+ * variables the world runtime already injects, and that `egress-service-cli.ts` already reads) and
+ * mints a short-lived HS256 access token PER CALL with only the grant that service needs — using this
+ * pack's own `mintAccessToken`, which has byte-level parity with `livekit-server-sdk`'s
+ * `AccessToken.toJwt()`. The secret never leaves the process; only the signed JWT is sent.
+ *
+ * EVERY request is guarded: the budget is charged BEFORE it goes out (`checkBudget`, which THROWS
+ * instead of returning once the ceiling or a persisted cooldown says stop) and the response is fed
+ * back (`recordCall`) so a `Retry-After` / 429 / rate-limit-exhaustion signal becomes a persisted
+ * cooldown that makes every later call fail fast WITHOUT touching LiveKit. There is deliberately NO
+ * option to disable the guard.
+ *
+ * No vendor SDK is imported: real-transport `fetch` plus this pack's own token minting keeps
+ * `livekit-server-sdk` a dev-only dependency, which the architecture guardrail requires.
+ */
+export function liveLiveKitExecute(
+  opts: {
+    url?: string;
+    apiKey?: string;
+    apiSecret?: string;
+    fetchImpl?: typeof fetch;
+    /** Seconds an issued token stays valid. Short by default, like the SDK's per-request tokens. */
+    tokenTtlSeconds?: number;
+    /** Unix SECONDS, for the token's nbf/exp. Injectable so tests are deterministic. */
+    nowSeconds?: () => number;
+    /** An existing budget to share across executes. Omit and one is constructed. Cannot be null. */
+    budget?: LiveKitBudget;
+    /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+    budgetOptions?: LiveKitBudgetOptions;
+  } = {},
+): LiveKitExecute {
+  const url = opts.url ?? process.env.LIVEKIT_URL ?? '';
+  if (!url) throw new Error('LIVEKIT_URL is not set — the live LiveKit client needs the project URL');
+  const apiKey = opts.apiKey ?? process.env.LIVEKIT_API_KEY ?? '';
+  const apiSecret = opts.apiSecret ?? process.env.LIVEKIT_API_SECRET ?? '';
+  if (!apiKey || !apiSecret) throw new Error('LIVEKIT_API_KEY and LIVEKIT_API_SECRET are not set — the live LiveKit client needs both to sign a token');
+  const origin = liveKitHttpOrigin(url);
+  const doFetch = opts.fetchImpl ?? fetch;
+  const ttlSeconds = opts.tokenTtlSeconds ?? 600;
+  const nowSeconds = opts.nowSeconds ?? (() => Math.floor(Date.now() / 1000));
+  // There is no value a caller can pass to end up with an unguarded execute. `null`/`undefined` (or
+  // omitting it) build the default budget; anything that is not a REAL `LiveKitBudget` is refused
+  // loudly rather than trusted — a duck-typed stand-in with a no-op `checkBudget` would otherwise be
+  // the one clean way around the guard.
+  if (opts.budget !== undefined && opts.budget !== null && !(opts.budget instanceof LiveKitBudget)) {
+    throw new Error('liveLiveKitExecute: `budget` must be a LiveKitBudget — refusing to build a live LiveKit client around an unverified rate guard');
+  }
+  // The default ledger is keyed by a hash of THIS api key — the Server API limit is per PROJECT and
+  // the key identifies the project, so a cwd-scoped ledger would hand the same project a fresh
+  // allowance per checkout/worktree/CI leg.
+  const budget = opts.budget instanceof LiveKitBudget
+    ? opts.budget
+    : new LiveKitBudget({ token: apiKey, ...(opts.budgetOptions ?? {}) });
+  return async (req) => {
+    // Validate the RPC name BEFORE charging: a malformed method is a caller bug, not vendor traffic,
+    // and it must not cost the project any of its allowance.
+    const path = liveKitTwirpPath(req.service, req.method);
+    const weight = liveKitCallWeight(req.service, req.method);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const grants = liveKitGrantFor(req.service, req.method);
+    const jwt = mintAccessToken({
+      apiKey,
+      apiSecret,
+      ttlSeconds,
+      nowSeconds: nowSeconds(),
+      ...(grants.video ? { video: grants.video } : {}),
+      ...(grants.sip ? { sip: grants.sip } : {}),
+    });
+    const res = await doFetch(`${origin}${path}`, {
+      method: 'POST', // every Twirp JSON call is a POST, including the read-only ones
+      headers: {
+        Authorization: `Bearer ${jwt}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      },
+      body: JSON.stringify(req.body ?? {}),
+    });
+    const headers = lowerCasedHeaders(res.headers);
+    const text = await res.text();
+    let data: unknown = null;
+    try { data = text ? JSON.parse(text) : null; } catch { data = { raw: text }; }
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // Retry-After beyond the cap is not something to sleep off) — the cooldown is persisted first
+    // either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer LiveKit ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, headers, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof LiveKitBudgetError) || !res.ok) throw error;
+    }
+    return { status: res.status, data };
+  };
+}
+
+/** Response headers as a plain lower-cased record — what the kernel's back-off reader expects. */
+function lowerCasedHeaders(h: Headers): Record<string, string> {
+  const out: Record<string, string> = {};
+  h.forEach((v: string, k: string) => { out[k.toLowerCase()] = v; });
+  return out;
+}
+
+// ── COLLECT (real → SyncResource[], no fold) ─────────────────────────────────────────
+// Private fetch helpers shared by the existing per-domain `pull*` functions (which fold their
+// own slice) and the D7 `syncLiveKitFromReal` entry point (which folds ALL slices in one syncPull).
+
+async function collectLiveKitSnapshot(execute: LiveKitExecute, roomNames: string[], occurredAt: string): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+  const rooms = await execute({ service: 'RoomService', method: 'ListRooms', body: { names: roomNames } });
+  if (rooms.status >= 200 && rooms.status < 300) {
+    for (const room of ((rooms.data as { rooms?: LiveKitRoom[] }).rooms ?? [])) {
+      resources.push({ type: 'room', id: roomId(room.name), fields: { ...room, id: roomId(room.name) } as unknown as Record<string, unknown> });
+      const participants = await execute({ service: 'RoomService', method: 'ListParticipants', body: { room: room.name } });
+      if (participants.status >= 200 && participants.status < 300) {
+        for (const participant of ((participants.data as { participants?: LiveKitParticipant[] }).participants ?? [])) {
+          const row = defaultParticipant(room.name, participant.identity, occurredAt, participant);
+          resources.push({ type: 'participant', id: row.id, fields: row as unknown as Record<string, unknown> });
+        }
+      }
+    }
+  }
+  const egress = await execute({ service: 'Egress', method: 'ListEgress', body: {} });
+  if (egress.status >= 200 && egress.status < 300) {
+    for (const row of ((egress.data as { items?: LiveKitEgress[] }).items ?? [])) {
+      const id = egressResourceId(row.egressId);
+      resources.push({ type: 'egress', id, fields: { ...row, id } as unknown as Record<string, unknown> });
+    }
+  }
+  const ingress = await execute({ service: 'Ingress', method: 'ListIngress', body: {} });
+  if (ingress.status >= 200 && ingress.status < 300) {
+    for (const row of ((ingress.data as { items?: LiveKitIngress[] }).items ?? [])) {
+      const id = ingressResourceId(row.ingressId);
+      resources.push({ type: 'ingress', id, fields: { ...row, id } as unknown as Record<string, unknown> });
+    }
+  }
+  return resources;
+}
+
+async function collectLiveKitSIP(execute: LiveKitExecute): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+  const inbound = await execute({ service: 'SIP', method: 'ListSIPInboundTrunk', body: {} });
+  if (inbound.status >= 200 && inbound.status < 300) {
+    for (const t of ((inbound.data as { items?: LiveKitSIPInboundTrunk[] }).items ?? [])) {
+      const id = `sip_inbound_trunk_${t.sipTrunkId}`;
+      resources.push({ type: 'sip_inbound_trunk', id, fields: { ...t, id } as unknown as Record<string, unknown> });
+    }
+  }
+  const outbound = await execute({ service: 'SIP', method: 'ListSIPOutboundTrunk', body: {} });
+  if (outbound.status >= 200 && outbound.status < 300) {
+    for (const t of ((outbound.data as { items?: LiveKitSIPOutboundTrunk[] }).items ?? [])) {
+      const id = `sip_outbound_trunk_${t.sipTrunkId}`;
+      resources.push({ type: 'sip_outbound_trunk', id, fields: { ...t, id } as unknown as Record<string, unknown> });
+    }
+  }
+  const rules = await execute({ service: 'SIP', method: 'ListSIPDispatchRule', body: {} });
+  if (rules.status >= 200 && rules.status < 300) {
+    for (const r of ((rules.data as { items?: LiveKitSIPDispatchRule[] }).items ?? [])) {
+      const id = `sip_dispatch_rule_${r.sipDispatchRuleId}`;
+      resources.push({ type: 'sip_dispatch_rule', id, fields: { ...r, id } as unknown as Record<string, unknown> });
+    }
+  }
+  return resources;
+}
+
+async function collectLiveKitAgentDispatch(execute: LiveKitExecute, roomNames: string[]): Promise<SyncResource[]> {
+  const resources: SyncResource[] = [];
+  for (const room of roomNames) {
+    const res = await execute({ service: 'AgentDispatchService', method: 'ListDispatch', body: { room } });
+    if (res.status < 200 || res.status >= 300) continue;
+    for (const a of ((res.data as { agentDispatches?: Array<{ id: string; agentName: string; room?: string; metadata?: string; state?: { createdAt?: string } }> }).agentDispatches ?? [])) {
+      const dispatchId = a.id;
+      const id = `agent_dispatch_${dispatchId}`;
+      const row: LiveKitAgentDispatch = {
+        id,
+        dispatchId,
+        agentName: a.agentName,
+        room: a.room ?? room,
+        metadata: a.metadata ?? '',
+        createdAt: a.state?.createdAt ?? '0',
+      };
+      resources.push({ type: 'agent_dispatch', id, fields: row as unknown as Record<string, unknown> });
+    }
+  }
+  return resources;
+}
+
+// ── PULL (per-domain — unchanged signatures; each folds its own slice) ────────────────
+export async function pullLiveKitSnapshot(execute: LiveKitExecute, roomNames: string[], opts: { root?: string; occurredAt?: string } = {}): Promise<void> {
+  const occurredAt = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  const resources = await collectLiveKitSnapshot(execute, roomNames, occurredAt);
+  fold(resources, { occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+}
+
+/**
+ * Pull SIP resources (inbound/outbound trunks + dispatch rules) through the
+ * injected client into local state. Idempotent: re-pulling the same snapshot
+ * records no new deltas.
+ */
+export async function pullLiveKitSIP(execute: LiveKitExecute, opts: { root?: string; occurredAt?: string } = {}): Promise<void> {
+  const occurredAt = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  const resources = await collectLiveKitSIP(execute);
+  fold(resources, { occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+}
+
+/**
+ * Pull agent dispatch resources for the given rooms through the injected client.
+ * Idempotent: re-pulling the same snapshot records no new deltas.
+ */
+export async function pullLiveKitAgentDispatch(execute: LiveKitExecute, roomNames: string[], opts: { root?: string; occurredAt?: string } = {}): Promise<void> {
+  const occurredAt = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  const resources = await collectLiveKitAgentDispatch(execute, roomNames);
+  fold(resources, { occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+}
+
+/**
+ * D7 consumer-facing pull entry point: gather resources across ALL LiveKit domains
+ * (rooms/participants/egress/ingress + SIP + agent dispatch) and fold them into the twin
+ * via a SINGLE syncPull. Domain inputs (room names) ride on `opts`. Idempotent: a re-pull
+ * of identical state appends no new deltas.
+ */
+/** One fold onto the head: protocol 2's observe, one batch, one instant. */
+function fold(resources: SyncResource[], opts: { root?: string; occurredAt: string }) {
+  return observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}`,
+  });
+}
+
+export async function syncLiveKitFromReal(
+  execute: LiveKitExecute,
+  opts: { root?: string; occurredAt?: string; roomNames?: string[] } = {},
+): Promise<{ observed: number; deltasAppended: number }> {
+  const occurredAt = opts.occurredAt ?? DEFAULT_OCCURRED_AT;
+  const roomNames = opts.roomNames ?? [];
+  const resources = [
+    ...(await collectLiveKitSnapshot(execute, roomNames, occurredAt)),
+    ...(await collectLiveKitSIP(execute)),
+    ...(await collectLiveKitAgentDispatch(execute, roomNames)),
+  ];
+  const result = fold(resources, { occurredAt, ...(opts.root !== undefined ? { root: opts.root } : {}) });
+  return { observed: result.observed, deltasAppended: result.appended };
+}
+
+export function liveKitRequestForAction(action: TwinAction): { service: LiveKitService; method: string; body?: unknown } | null {
+  const fields = action.fields as Record<string, unknown>;
+  if (action.operation === 'room.update_metadata') return { service: 'RoomService', method: 'UpdateRoomMetadata', body: { room: fields.name, metadata: fields.metadata ?? '' } };
+  if (action.operation === 'egress.stop') return { service: 'Egress', method: 'StopEgress', body: { egressId: fields.egressId } };
+  return null;
+}
+
+export async function pushLiveKitAction(action: TwinAction, execute: LiveKitExecute): Promise<boolean> {
+  const req = liveKitRequestForAction(action);
+  if (!req) return false;
+  const result = await execute(req);
+  if (result.status < 200 || result.status >= 300) return false;
+  const data = result.data as Record<string, unknown>;
+  // the vendor's answer has to SHOW the change, or it did not happen
+  if (action.operation === 'room.update_metadata' && data.metadata !== (action.fields as Record<string, unknown>).metadata) return false;
+  if (action.operation === 'egress.stop' && data.status !== EGRESS_STATUS.COMPLETE) return false;
+  return true;
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's: LiveKit's Twirp RPCs, carried by the head. */
+export function liveKitExecuteOver(execute: RemoteExecute): LiveKitExecute {
+  return async ({ service, method, body }) => {
+    const res = await execute({
+      method: 'POST', path: liveKitTwirpPath(service, method),
+      headers: { accept: 'application/json', 'content-type': 'application/json' },
+      body: JSON.stringify(body ?? {}),
+    });
+    let data: unknown = {};
+    if (res.body) { try { data = JSON.parse(res.body); } catch { data = { msg: res.body }; } }
+    return { status: res.status, data };
+  };
+}
+/** The refresh adapter: pull the rooms, egresses and ingresses this credential can see. */
+export async function syncLiveKitFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string } = {}): Promise<{ observed: number; deltasAppended: number }> {
+  return syncLiveKitFromReal(liveKitExecuteOver(execute), {
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    ...(opts.occurredAt !== undefined ? { occurredAt: opts.occurredAt } : {}),
+  });
+}
+/** The perform adapter: one entry crosses to LiveKit, or settles with the reason it never could. A room's
+ *  metadata update and an egress stop are checked against the vendor's ANSWER, not its status code. */
+export async function performLiveKitAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  const req = liveKitRequestForAction(action);
+  if (!req) return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type} is the twin's own record — nothing at LiveKit to write` } };
+  const ok = await pushLiveKitAction(action, liveKitExecuteOver(execute));
+  if (!ok) throw new Error(`livekit perform ${action.operation ?? action.subject.type} refused: the answer did not show the change`);
+  return { externalId: action.subject.id };
+}