@volter/twin-livekit 0.1.0

package/src/livekit-capabilities.ts

@@ -0,0 +1,789 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { applyTwinWrite, pendingActions, projectResources } from '@volter/world-core';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
+import { EGRESS_STATUS, INGRESS_INPUT, INGRESS_STATUS, TRACK_SOURCE } from './livekit-data.ts';
+import { pullLiveKitAgentDispatch, pullLiveKitSIP, pullLiveKitSnapshot,  } from './livekit-connector.ts';
+import { performPending } from './livekit-perform-harness.ts';
+import { handleLiveKitTwinRequest } from './livekit-twin.ts';
+import { mintAccessToken, verifyAccessToken } from './livekit-token.ts';
+import { buildWebhookBody, signWebhookHeader, verifyWebhook } from './livekit-webhook.ts';
+
+type Body = Record<string, any>;
+type Step = {
+  service?: string;
+  method?: string;
+  b?: unknown;
+  readOnly?: boolean;
+  authToken?: string;
+  apiKeys?: Record<string, string>;
+  nowSeconds?: number;
+  maxActiveEgress?: number;
+};
+
+const API_KEY = 'devkey';
+const API_SECRET = 'secretsecretsecretsecretsecretsecret';
+
+async function withRoot(fn: (h: (step: Step) => Promise<{ status: number; body: unknown }>, root: string) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'livekit-cap-'));
+  const h = (step: Step) => handleLiveKitTwinRequest({
+    method: 'POST',
+    path: `/twirp/livekit.${step.service ?? 'RoomService'}/${step.method ?? 'ListRooms'}`,
+    body: step.b === undefined ? '{}' : JSON.stringify(step.b),
+    root,
+    readOnly: step.readOnly,
+    occurredAt: '1970-01-01T00:00:00.000Z',
+    ...(step.authToken !== undefined ? { authToken: step.authToken } : {}),
+    ...(step.apiKeys !== undefined ? { apiKeys: step.apiKeys } : {}),
+    ...(step.nowSeconds !== undefined ? { nowSeconds: step.nowSeconds } : {}),
+    ...(step.maxActiveEgress !== undefined ? { maxActiveEgress: step.maxActiveEgress } : {}),
+  });
+  try {
+    return await verifyBoundary('livekit.withRoot', () => fn(h, root));
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const done = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, dimension: CapabilitySpec['dimension'], tier: CapabilitySpec['tier']): CapabilitySpec =>
+  ({ id, area, title, dimension, tier, expected: 'todo' });
+
+export const LIVEKIT_CAPABILITIES: CapabilitySpec[] = [
+  todo('livekit.webhooks.delivery', 'webhooks', 'Outbound webhook delivery: POST the signed event bodies the twin already builds to the configured webhookUrl, with the documented retry schedule', 'api', 'common'),
+
+  done('livekit.rooms.create', 'rooms', 'RoomService CreateRoom creates a room with SDK-shaped fields', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ method: 'CreateRoom', b: { name: 'cap-room', emptyTimeout: 600, maxParticipants: 10 } });
+      return r.status === 200 && (r.body as Body).name === 'cap-room' && (r.body as Body).emptyTimeout === 600 && (r.body as Body).maxParticipants === 10;
+    })),
+  done('livekit.rooms.create_validation', 'rooms', 'CreateRoom rejects missing room name', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ method: 'CreateRoom', b: {} });
+      return r.status === 400 && (r.body as Body).code === 'invalid_argument';
+    })),
+  done('livekit.rooms.list_all', 'rooms', 'ListRooms returns all local active rooms', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'one' } });
+      await h({ method: 'CreateRoom', b: { name: 'two' } });
+      const r = await h({ method: 'ListRooms', b: {} });
+      return r.status === 200 && (r.body as Body).rooms?.map((room: Body) => room.name).sort().join(',') === 'one,two';
+    })),
+  done('livekit.rooms.list_filter', 'rooms', 'ListRooms filters by room names', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'one' } });
+      await h({ method: 'CreateRoom', b: { name: 'two' } });
+      const r = await h({ method: 'ListRooms', b: { names: ['two'] } });
+      return r.status === 200 && (r.body as Body).rooms?.length === 1 && (r.body as Body).rooms[0].name === 'two';
+    })),
+  done('livekit.rooms.update_metadata', 'rooms', 'UpdateRoomMetadata persists metadata', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'meta-room' } });
+      const updated = await h({ method: 'UpdateRoomMetadata', b: { room: 'meta-room', metadata: '{"egressActive":true}' } });
+      const listed = await h({ method: 'ListRooms', b: { names: ['meta-room'] } });
+      return updated.status === 200 && (updated.body as Body).metadata === '{"egressActive":true}' && (listed.body as Body).rooms?.[0]?.metadata === '{"egressActive":true}';
+    })),
+  done('livekit.rooms.update_missing', 'rooms', 'UpdateRoomMetadata returns not_found for unknown room', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ method: 'UpdateRoomMetadata', b: { room: 'missing', metadata: '{}' } });
+      return r.status === 404 && (r.body as Body).code === 'not_found';
+    })),
+  done('livekit.rooms.delete', 'rooms', 'DeleteRoom removes room from ListRooms', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'delete-me' } });
+      const deleted = await h({ method: 'DeleteRoom', b: { room: 'delete-me' } });
+      const listed = await h({ method: 'ListRooms', b: { names: ['delete-me'] } });
+      return deleted.status === 200 && (listed.body as Body).rooms?.length === 0;
+    })),
+  done('livekit.rooms.recreate_after_delete', 'rooms', 'CreateRoom can recreate a deleted room name', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'recreate-me' } });
+      await h({ method: 'DeleteRoom', b: { room: 'recreate-me' } });
+      await h({ method: 'CreateRoom', b: { name: 'recreate-me' } });
+      const listed = await h({ method: 'ListRooms', b: { names: ['recreate-me'] } });
+      return (listed.body as Body).rooms?.length === 1 && (listed.body as Body).rooms[0].name === 'recreate-me';
+    })),
+  done('livekit.readonly.rejects_room_write', 'honesty', 'readOnly rejects room writes', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const r = await h({ method: 'CreateRoom', b: { name: 'ro' }, readOnly: true });
+      return r.status === 405 && (r.body as Body).code === 'permission_denied';
+    })),
+
+  done('livekit.participants.list', 'participants', 'ListParticipants returns locally seeded participants', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'p-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'p-room', identity: 'tester-1' } });
+      const r = await h({ method: 'ListParticipants', b: { room: 'p-room' } });
+      return r.status === 200 && (r.body as Body).participants?.[0]?.identity === 'tester-1';
+    })),
+  done('livekit.participants.counts_room', 'participants', 'Room numParticipants reflects locally seeded participants', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'count-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'count-room', identity: 'tester-1' } });
+      const r = await h({ method: 'ListRooms', b: { names: ['count-room'] } });
+      return (r.body as Body).rooms?.[0]?.numParticipants === 1;
+    })),
+  done('livekit.participants.get', 'participants', 'GetParticipant returns one locally seeded participant by identity', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'get-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'get-room', identity: 'tester-1', name: 'Tester One' } });
+      const r = await h({ method: 'GetParticipant', b: { room: 'get-room', identity: 'tester-1' } });
+      return r.status === 200 && (r.body as Body).name === 'Tester One';
+    })),
+  done('livekit.participants.screen_share', 'participants', 'Locally seeded participant tracks expose SCREEN_SHARE source and muted state', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'share-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'share-room', identity: 'tester-1', tracks: [{ source: 'SCREEN_SHARE', muted: false }] } });
+      const r = await h({ method: 'ListParticipants', b: { room: 'share-room' } });
+      const track = (r.body as Body).participants?.[0]?.tracks?.[0];
+      return r.status === 200 && track?.source === TRACK_SOURCE.SCREEN_SHARE && track?.muted === false;
+    })),
+  done('livekit.participants.mute_track', 'participants', 'MutePublishedTrack toggles a published track', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'mute-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'mute-room', identity: 'tester-1', tracks: [{ sid: 'TR_screen', source: 'SCREEN_SHARE', muted: false }] } });
+      const muted = await h({ method: 'MutePublishedTrack', b: { room: 'mute-room', identity: 'tester-1', trackSid: 'TR_screen', muted: true } });
+      const got = await h({ method: 'GetParticipant', b: { room: 'mute-room', identity: 'tester-1' } });
+      return muted.status === 200 && (muted.body as Body).track?.muted === true && (got.body as Body).tracks?.[0]?.muted === true;
+    })),
+  done('livekit.participants.remove', 'participants', 'RemoveParticipant hides participant from ListParticipants', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'remove-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'remove-room', identity: 'tester-1' } });
+      const removed = await h({ method: 'RemoveParticipant', b: { room: 'remove-room', identity: 'tester-1' } });
+      const listed = await h({ method: 'ListParticipants', b: { room: 'remove-room' } });
+      return removed.status === 200 && (listed.body as Body).participants?.length === 0;
+    })),
+
+  done('livekit.egress.start_room_composite', 'egress', 'StartRoomCompositeEgress records an active egress', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'egress-room' } });
+      const r = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'egress-room', fileOutputs: [{ filepath: 'recordings/job/eg.mp4' }], videoOnly: true } });
+      const second = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'egress-room', fileOutputs: [{ filepath: 'recordings/job/eg.mp4' }], videoOnly: true } });
+      return r.status === 200 && typeof (r.body as Body).egressId === 'string' && (r.body as Body).status === EGRESS_STATUS.ACTIVE && (r.body as Body).roomName === 'egress-room'
+        && (second.body as Body).egressId !== (r.body as Body).egressId;
+    })),
+  done('livekit.egress.list_by_id', 'egress', 'ListEgress filters by egressId', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'egress-list' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'egress-list' } });
+      const egressId = (started.body as Body).egressId;
+      // guard against a sabotaged/empty handler: the started egressId must actually be a real id,
+      // not compare undefined-to-undefined.
+      if (started.status !== 200 || typeof egressId !== 'string' || egressId.length === 0) return false;
+      const listed = await h({ service: 'Egress', method: 'ListEgress', b: { egressId } });
+      const items = (listed.body as Body).items as Body[] | undefined;
+      return listed.status === 200 && Array.isArray(items) && items.length === 1 && items[0]!.egressId === egressId;
+    })),
+  done('livekit.egress.stop_complete', 'egress', 'StopEgress transitions egress to COMPLETE', 'api', 'core', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'stop-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'stop-room' } });
+      const stopped = await h({ service: 'Egress', method: 'StopEgress', b: { egressId: (started.body as Body).egressId } });
+      return stopped.status === 200 && (stopped.body as Body).status === EGRESS_STATUS.COMPLETE && typeof (stopped.body as Body).endedAt === 'string';
+    })),
+  done('livekit.egress.active_filter', 'egress', 'ListEgress active filter excludes completed egresses', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'active-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'active-room' } });
+      await h({ service: 'Egress', method: 'StopEgress', b: { egressId: (started.body as Body).egressId } });
+      const listed = await h({ service: 'Egress', method: 'ListEgress', b: { active: true } });
+      return listed.status === 200 && (listed.body as Body).items?.length === 0;
+    })),
+  done('livekit.egress.update_layout', 'egress', 'UpdateLayout persists egress layout', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'layout-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'layout-room' } });
+      const updated = await h({ service: 'Egress', method: 'UpdateLayout', b: { egressId: (started.body as Body).egressId, layout: 'speaker' } });
+      return updated.status === 200 && (updated.body as Body).roomComposite?.layout === 'speaker';
+    })),
+  done('livekit.unmodeled.404', 'honesty', 'Unmodeled Twirp methods fail with not_found', 'api', 'core', () =>
+    withRoot(async (h) => {
+      const r = await h({ method: 'TeleportRoom', b: {} });
+      return r.status === 404 && (r.body as Body).code === 'not_found';
+    })),
+
+  done('livekit.connector.pull', 'connector', 'Connector pulls rooms, participants, and egress through injected client', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'livekit-connector-cap-'));
+    try {
+      await pullLiveKitSnapshot(async (req) => {
+        if (req.service === 'RoomService' && req.method === 'ListRooms') return { status: 200, data: { rooms: [{ name: 'remote-room', sid: 'RM_remote', metadata: '', emptyTimeout: 300 }] } };
+        if (req.service === 'RoomService' && req.method === 'ListParticipants') return { status: 200, data: { participants: [{ identity: 'remote-user', tracks: [] }] } };
+        return { status: 200, data: { items: [{ egressId: 'EG_remote', roomName: 'remote-room', status: EGRESS_STATUS.ACTIVE }] } };
+      }, ['remote-room'], { root });
+      await pullLiveKitSnapshot(async (req) => {
+        if (req.service === 'RoomService' && req.method === 'ListRooms') return { status: 200, data: { rooms: [{ name: 'remote-room', sid: 'RM_remote', metadata: '', emptyTimeout: 300 }] } };
+        if (req.service === 'RoomService' && req.method === 'ListParticipants') return { status: 200, data: { participants: [{ identity: 'remote-user', tracks: [] }] } };
+        return { status: 200, data: { items: [{ egressId: 'EG_remote', roomName: 'remote-room', status: EGRESS_STATUS.ACTIVE }] } };
+      }, ['remote-room'], { root });
+      const rows = projectResources('livekit', root);
+      return rows.some((r) => r.type === 'room' && (r as Body).name === 'remote-room')
+        && rows.some((r) => r.type === 'participant' && (r as Body).identity === 'remote-user')
+        && rows.filter((r) => r.type === 'egress' && (r as Body).egressId === 'EG_remote').length === 1;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('livekit.connector.push', 'connector', 'Connector confirms pending room metadata pushes idempotently', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'livekit-connector-push-cap-'));
+    try {
+      await applyTwinWrite('livekit', {
+        operation: 'room.update_metadata',
+        subjectType: 'room',
+        subjectId: 'room_push',
+        fields: { id: 'room_push', name: 'push-room', metadata: '{"ok":true}' },
+        occurredAt: '1970-01-01T00:00:00.000Z',
+        actor: { kind: 'system' },
+      }, root);
+      const pushed = await performPending(async () => ({ status: 200, data: { name: 'push-room', metadata: '{"ok":true}' } }), { root });
+      const again = await performPending(async () => ({ status: 200, data: {} }), { root });
+      return pushed === 1 && again === 0 && pendingActions('livekit', root).length === 0;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+
+  done('livekit.rooms.forward_participant', 'rooms', 'ForwardParticipant mirrors a participant into a destination room (source retained, mirror cannot publish)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'fwd-src' } });
+      await h({ method: 'CreateRoom', b: { name: 'fwd-dst' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'fwd-src', identity: 'caller', tracks: [{ sid: 'TR_a', source: 'CAMERA' }] } });
+      const fwd = await h({ method: 'ForwardParticipant', b: { room: 'fwd-src', identity: 'caller', destinationRoom: 'fwd-dst' } });
+      // original retained in source, mirror appears in destination
+      const src = await h({ method: 'GetParticipant', b: { room: 'fwd-src', identity: 'caller' } });
+      const dst = await h({ method: 'GetParticipant', b: { room: 'fwd-dst', identity: 'caller' } });
+      const noDst = await h({ method: 'ForwardParticipant', b: { room: 'fwd-src', identity: 'caller' } });
+      const ghost = await h({ method: 'ForwardParticipant', b: { room: 'fwd-src', identity: 'nobody', destinationRoom: 'fwd-dst' } });
+      const dup = await h({ method: 'ForwardParticipant', b: { room: 'fwd-src', identity: 'caller', destinationRoom: 'fwd-dst' } });
+      return fwd.status === 200 && src.status === 200 && dst.status === 200
+        && (dst.body as Body).isPublisher === false && (dst.body as Body).permission?.canPublish === false
+        && noDst.status === 400 && ghost.status === 404 && dup.status === 409;
+    })),
+  done('livekit.rooms.move_participant', 'rooms', 'MoveParticipant relocates a participant (left source, present in destination)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'mv-src' } });
+      await h({ method: 'CreateRoom', b: { name: 'mv-dst' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'mv-src', identity: 'mover', name: 'Mover' } });
+      const mv = await h({ method: 'MoveParticipant', b: { room: 'mv-src', identity: 'mover', destinationRoom: 'mv-dst' } });
+      const srcList = await h({ method: 'ListParticipants', b: { room: 'mv-src' } });
+      const dst = await h({ method: 'GetParticipant', b: { room: 'mv-dst', identity: 'mover' } });
+      const noDst = await h({ method: 'MoveParticipant', b: { room: 'mv-src', identity: 'mover' } });
+      const ghost = await h({ method: 'MoveParticipant', b: { room: 'mv-src', identity: 'gone', destinationRoom: 'mv-dst' } });
+      return mv.status === 200 && (srcList.body as Body).participants?.length === 0
+        && dst.status === 200 && (dst.body as Body).name === 'Mover'
+        && noDst.status === 400 && ghost.status === 404;
+    })),
+
+  done('livekit.rooms.update_subscriptions', 'rooms', 'UpdateSubscriptions adds/removes participant track subscriptions', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'sub-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'sub-room', identity: 'sub-1' } });
+      const sub = await h({ method: 'UpdateSubscriptions', b: { room: 'sub-room', identity: 'sub-1', trackSids: ['TR_a', 'TR_b'], subscribe: true } });
+      const afterSub = await h({ method: 'GetParticipant', b: { room: 'sub-room', identity: 'sub-1' } });
+      const subbed = ((afterSub.body as Body).subscribedTracks ?? []).slice().sort().join(',');
+      const unsub = await h({ method: 'UpdateSubscriptions', b: { room: 'sub-room', identity: 'sub-1', trackSids: ['TR_a'], subscribe: false } });
+      const afterUnsub = await h({ method: 'GetParticipant', b: { room: 'sub-room', identity: 'sub-1' } });
+      const missing = await h({ method: 'UpdateSubscriptions', b: { room: 'sub-room', identity: 'ghost', trackSids: ['TR_a'], subscribe: true } });
+      return sub.status === 200 && subbed === 'TR_a,TR_b' && unsub.status === 200
+        && ((afterUnsub.body as Body).subscribedTracks ?? []).join(',') === 'TR_b' && missing.status === 404;
+    })),
+  done('livekit.rooms.send_data', 'rooms', 'SendData validates room+payload and acks; unknown room/empty payload fail', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'data-room' } });
+      const ok = await h({ method: 'SendData', b: { room: 'data-room', data: 'aGVsbG8=', kind: 0, topic: 'chat' } });
+      const noRoom = await h({ method: 'SendData', b: { room: 'missing', data: 'aGVsbG8=' } });
+      const noData = await h({ method: 'SendData', b: { room: 'data-room' } });
+      return ok.status === 200 && noRoom.status === 404 && (noRoom.body as Body).code === 'not_found'
+        && noData.status === 400 && (noData.body as Body).code === 'invalid_argument';
+    })),
+  done('livekit.rooms.permission_update', 'participants', 'UpdateParticipant atomically replaces permission grants', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'perm-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'perm-room', identity: 'perm-1' } });
+      const updated = await h({ method: 'UpdateParticipant', b: { room: 'perm-room', identity: 'perm-1', permission: { canSubscribe: true, canPublish: false, canPublishData: false, hidden: true } } });
+      const perm = (updated.body as Body).permission;
+      return updated.status === 200 && perm?.canSubscribe === true && perm?.canPublish === false && perm?.hidden === true && (updated.body as Body).isPublisher === false;
+    })),
+
+  done('livekit.rooms.subscription_permissions', 'participants', 'Subscription set is tracked per participant across toggles', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'subperm-room' } });
+      await h({ service: 'Twin', method: 'UpsertParticipant', b: { roomName: 'subperm-room', identity: 'sp-1' } });
+      await h({ method: 'UpdateSubscriptions', b: { room: 'subperm-room', identity: 'sp-1', trackSids: ['TR_x'], subscribe: true } });
+      await h({ method: 'UpdateSubscriptions', b: { room: 'subperm-room', identity: 'sp-1', trackSids: ['TR_x'], subscribe: true } });
+      const got = await h({ method: 'GetParticipant', b: { room: 'subperm-room', identity: 'sp-1' } });
+      // idempotent: re-subscribing the same sid does not duplicate it
+      return ((got.body as Body).subscribedTracks ?? []).filter((s: string) => s === 'TR_x').length === 1;
+    })),
+
+  done('livekit.egress.web', 'egress', 'StartWebEgress records a web-source egress with no backing room', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const started = await h({ service: 'Egress', method: 'StartWebEgress', b: { url: 'https://example.com/live', streamOutputs: [{ urls: ['rtmp://a/b'] }] } });
+      const noUrl = await h({ service: 'Egress', method: 'StartWebEgress', b: {} });
+      return started.status === 200 && (started.body as Body).web?.url === 'https://example.com/live'
+        && (started.body as Body).status === EGRESS_STATUS.ACTIVE && noUrl.status === 400;
+    })),
+  done('livekit.egress.participant', 'egress', 'StartParticipantEgress requires identity and tags request case', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'pe-room' } });
+      const started = await h({ service: 'Egress', method: 'StartParticipantEgress', b: { roomName: 'pe-room', identity: 'pe-1' } });
+      const noId = await h({ service: 'Egress', method: 'StartParticipantEgress', b: { roomName: 'pe-room' } });
+      return started.status === 200 && (started.body as Body).participant?.identity === 'pe-1' && noId.status === 400;
+    })),
+  done('livekit.egress.track_composite', 'egress', 'StartTrackCompositeEgress requires a track id and tags request case', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'tc-room' } });
+      const started = await h({ service: 'Egress', method: 'StartTrackCompositeEgress', b: { roomName: 'tc-room', videoTrackId: 'TR_v', audioTrackId: 'TR_a' } });
+      const noTrack = await h({ service: 'Egress', method: 'StartTrackCompositeEgress', b: { roomName: 'tc-room' } });
+      return started.status === 200 && (started.body as Body).trackComposite?.videoTrackId === 'TR_v' && noTrack.status === 400;
+    })),
+  done('livekit.egress.track', 'egress', 'StartTrackEgress requires a track id and tags request case', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'te-room' } });
+      const started = await h({ service: 'Egress', method: 'StartTrackEgress', b: { roomName: 'te-room', trackId: 'TR_only' } });
+      const noTrack = await h({ service: 'Egress', method: 'StartTrackEgress', b: { roomName: 'te-room' } });
+      return started.status === 200 && (started.body as Body).track?.trackId === 'TR_only' && noTrack.status === 400;
+    })),
+  done('livekit.egress.update_stream', 'egress', 'UpdateStream adds and removes output URLs on an active egress', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'us-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'us-room', streamOutputs: [{ urls: ['rtmp://a/1'] }] } });
+      const id = (started.body as Body).egressId;
+      const added = await h({ service: 'Egress', method: 'UpdateStream', b: { egressId: id, addOutputUrls: ['rtmp://b/2'] } });
+      const urls1 = ((added.body as Body).streamResults ?? []).map((s: Body) => s.url).sort().join(',');
+      const removed = await h({ service: 'Egress', method: 'UpdateStream', b: { egressId: id, removeOutputUrls: ['rtmp://a/1'] } });
+      const urls2 = ((removed.body as Body).streamResults ?? []).map((s: Body) => s.url).join(',');
+      await h({ service: 'Egress', method: 'StopEgress', b: { egressId: id } });
+      const afterStop = await h({ service: 'Egress', method: 'UpdateStream', b: { egressId: id, addOutputUrls: ['rtmp://c/3'] } });
+      return added.status === 200 && urls1 === 'rtmp://a/1,rtmp://b/2' && urls2 === 'rtmp://b/2' && afterStop.status === 412;
+    })),
+  done('livekit.egress.failure_states', 'egress', 'Egress can transition to FAILED/ABORTED/LIMIT_REACHED terminal states', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'fail-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'fail-room' } });
+      const id = (started.body as Body).egressId;
+      const failed = await h({ service: 'Egress', method: 'FailEgress', b: { egressId: id, status: EGRESS_STATUS.FAILED, error: 'compositor crashed', errorCode: 2 } });
+      const listActive = await h({ service: 'Egress', method: 'ListEgress', b: { active: true } });
+      const cannotStop = await h({ service: 'Egress', method: 'StopEgress', b: { egressId: id } });
+      const badState = await h({ service: 'Egress', method: 'FailEgress', b: { egressId: id, status: EGRESS_STATUS.COMPLETE } });
+      return failed.status === 200 && (failed.body as Body).status === EGRESS_STATUS.FAILED
+        && (failed.body as Body).error === 'compositor crashed' && (listActive.body as Body).items?.length === 0
+        && cannotStop.status === 412 && badState.status === 400;
+    })),
+  done('livekit.egress.segment_outputs', 'egress', 'Segment outputs are persisted on the egress request', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'seg-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'seg-room', segmentOutputs: [{ filenamePrefix: 'seg/out', playlistName: 'index.m3u8', segmentDuration: 6 }] } });
+      const listed = await h({ service: 'Egress', method: 'ListEgress', b: { egressId: (started.body as Body).egressId } });
+      const seg = (listed.body as Body).items?.[0]?.roomComposite?.segmentOutputs?.[0];
+      return started.status === 200 && seg?.playlistName === 'index.m3u8' && seg?.segmentDuration === 6;
+    })),
+  done('livekit.egress.image_outputs', 'egress', 'Image (thumbnail) outputs are persisted on the egress request and round-trip via ListEgress', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'img-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'img-room', imageOutputs: [{ captureInterval: 5, width: 1280, height: 720, filenamePrefix: 'thumb/img', imagePrefix: 'thumb' }] } });
+      const listed = await h({ service: 'Egress', method: 'ListEgress', b: { egressId: (started.body as Body).egressId } });
+      const img = (listed.body as Body).items?.[0]?.roomComposite?.imageOutputs?.[0];
+      // imageResults is always present (empty offline — no rendered snapshot bytes).
+      return started.status === 200 && img?.captureInterval === 5 && img?.filenamePrefix === 'thumb/img'
+        && Array.isArray((listed.body as Body).items?.[0]?.imageResults);
+    })),
+  done('livekit.egress.webhook_config', 'egress', 'Per-egress webhook config (webhookUrl) is persisted on the request and round-trips via ListEgress', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'wh-room' } });
+      const started = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'wh-room', webhookUrl: 'https://hooks.example.com/egress' } });
+      const listed = await h({ service: 'Egress', method: 'ListEgress', b: { egressId: (started.body as Body).egressId } });
+      return started.status === 200 && (listed.body as Body).items?.[0]?.roomComposite?.webhookUrl === 'https://hooks.example.com/egress';
+    })),
+
+  done('livekit.ingress.create', 'ingress', 'CreateIngress mints stream key/url and requires participant identity', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'RTMP_INPUT', roomName: 'live', participantIdentity: 'streamer', name: 'My Ingress' } });
+      const noId = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'RTMP_INPUT', roomName: 'live' } });
+      const noUrl = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'URL_INPUT', roomName: 'live', participantIdentity: 'streamer' } });
+      const b = created.body as Body;
+      return created.status === 200 && typeof b.ingressId === 'string' && b.ingressId.startsWith('IN_')
+        && b.streamKey && b.url.startsWith('rtmp://') && b.inputType === INGRESS_INPUT.RTMP_INPUT
+        && b.state?.status === INGRESS_STATUS.ENDPOINT_INACTIVE && noId.status === 400 && noUrl.status === 400;
+    })),
+  done('livekit.ingress.update', 'ingress', 'UpdateIngress mutates fields and toggles transcoding', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'RTMP_INPUT', roomName: 'r1', participantIdentity: 'p1' } });
+      const id = (created.body as Body).ingressId;
+      const updated = await h({ service: 'Ingress', method: 'UpdateIngress', b: { ingressId: id, name: 'renamed', roomName: 'r2', enableTranscoding: false } });
+      const missing = await h({ service: 'Ingress', method: 'UpdateIngress', b: { ingressId: 'IN_nope', name: 'x' } });
+      const b = updated.body as Body;
+      return updated.status === 200 && b.name === 'renamed' && b.roomName === 'r2' && b.enableTranscoding === false && b.bypassTranscoding === true && missing.status === 404;
+    })),
+  done('livekit.ingress.list', 'ingress', 'ListIngress filters by room and ingress id, excludes deleted', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'RTMP_INPUT', roomName: 'a', participantIdentity: 'p1' } });
+      const c2 = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'WHIP_INPUT', roomName: 'b', participantIdentity: 'p2' } });
+      const all = await h({ service: 'Ingress', method: 'ListIngress', b: {} });
+      const byRoom = await h({ service: 'Ingress', method: 'ListIngress', b: { roomName: 'b' } });
+      const byId = await h({ service: 'Ingress', method: 'ListIngress', b: { ingressId: (c2.body as Body).ingressId } });
+      return (all.body as Body).items?.length === 2 && (byRoom.body as Body).items?.length === 1
+        && (byRoom.body as Body).items[0].roomName === 'b' && (byId.body as Body).items?.length === 1;
+    })),
+  done('livekit.ingress.delete', 'ingress', 'DeleteIngress removes ingress from ListIngress and completes its state', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const created = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'RTMP_INPUT', roomName: 'a', participantIdentity: 'p1' } });
+      const id = (created.body as Body).ingressId;
+      const deleted = await h({ service: 'Ingress', method: 'DeleteIngress', b: { ingressId: id } });
+      const listed = await h({ service: 'Ingress', method: 'ListIngress', b: {} });
+      const missing = await h({ service: 'Ingress', method: 'DeleteIngress', b: { ingressId: id } });
+      return deleted.status === 200 && (deleted.body as Body).state?.status === INGRESS_STATUS.ENDPOINT_COMPLETE
+        && (listed.body as Body).items?.length === 0 && missing.status === 404;
+    })),
+  done('livekit.ingress.rtmp_whip', 'ingress', 'RTMP defaults to transcoding+streamKey; WHIP defaults to bypass', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const rtmp = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'RTMP_INPUT', roomName: 'r', participantIdentity: 'p1' } });
+      const whip = await h({ service: 'Ingress', method: 'CreateIngress', b: { inputType: 'WHIP_INPUT', roomName: 'r', participantIdentity: 'p2' } });
+      const r = rtmp.body as Body;
+      const w = whip.body as Body;
+      return r.inputType === INGRESS_INPUT.RTMP_INPUT && r.enableTranscoding === true && r.url.startsWith('rtmp://') && r.streamKey
+        && w.inputType === INGRESS_INPUT.WHIP_INPUT && w.enableTranscoding === false && w.bypassTranscoding === true && w.url.startsWith('https://');
+    })),
+  done('livekit.sip.inbound_trunks', 'sip', 'CreateSIPInboundTrunk + list/delete; create requires a number, list filters by id/number', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const created = await h({ service: 'SIP', method: 'CreateSIPInboundTrunk', b: { trunk: { name: 'main', numbers: ['+15551230000'], allowedNumbers: ['+1*'], authUsername: 'u', authPassword: 'p' } } });
+      const id = (created.body as Body).sipTrunkId;
+      const noNumber = await h({ service: 'SIP', method: 'CreateSIPInboundTrunk', b: { trunk: { name: 'bad', numbers: [] } } });
+      const listed = await h({ service: 'SIP', method: 'ListSIPInboundTrunk', b: {} });
+      const byNumber = await h({ service: 'SIP', method: 'ListSIPInboundTrunk', b: { numbers: ['+15551230000'] } });
+      const byMissNum = await h({ service: 'SIP', method: 'ListSIPInboundTrunk', b: { numbers: ['+19999999999'] } });
+      const deleted = await h({ service: 'SIP', method: 'DeleteSIPTrunk', b: { sipTrunkId: id } });
+      const afterDelete = await h({ service: 'SIP', method: 'ListSIPInboundTrunk', b: {} });
+      const deleteMissing = await h({ service: 'SIP', method: 'DeleteSIPTrunk', b: { sipTrunkId: id } });
+      return created.status === 200 && typeof id === 'string' && id.startsWith('ST_')
+        && (created.body as Body).numbers?.[0] === '+15551230000' && (created.body as Body).authUsername === 'u'
+        && noNumber.status === 400 && (listed.body as Body).items?.length === 1
+        && (byNumber.body as Body).items?.length === 1 && (byMissNum.body as Body).items?.length === 0
+        && deleted.status === 200 && (afterDelete.body as Body).items?.length === 0 && deleteMissing.status === 404;
+    })),
+  done('livekit.sip.outbound_trunks', 'sip', 'CreateSIPOutboundTrunk + list/delete; create requires an address, transport normalizes', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const created = await h({ service: 'SIP', method: 'CreateSIPOutboundTrunk', b: { trunk: { name: 'pstn', address: 'sip.provider.com', numbers: ['+15557654321'], transport: 'SIP_TRANSPORT_TCP', destinationCountry: 'US' } } });
+      const id = (created.body as Body).sipTrunkId;
+      const noAddr = await h({ service: 'SIP', method: 'CreateSIPOutboundTrunk', b: { trunk: { name: 'bad' } } });
+      const listed = await h({ service: 'SIP', method: 'ListSIPOutboundTrunk', b: {} });
+      const byId = await h({ service: 'SIP', method: 'ListSIPOutboundTrunk', b: { trunkIds: [id] } });
+      const deleted = await h({ service: 'SIP', method: 'DeleteSIPTrunk', b: { sipTrunkId: id } });
+      const afterDelete = await h({ service: 'SIP', method: 'ListSIPOutboundTrunk', b: {} });
+      return created.status === 200 && (created.body as Body).address === 'sip.provider.com'
+        && (created.body as Body).transport === 'SIP_TRANSPORT_TCP' && (created.body as Body).destinationCountry === 'US'
+        && noAddr.status === 400 && (listed.body as Body).items?.length === 1 && (byId.body as Body).items?.length === 1
+        && deleted.status === 200 && (afterDelete.body as Body).items?.length === 0;
+    })),
+  done('livekit.sip.dispatch_rules', 'sip', 'CreateSIPDispatchRule (direct + individual oneof) + list/delete; direct requires a roomName', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const direct = await h({ service: 'SIP', method: 'CreateSIPDispatchRule', b: { rule: { dispatchRuleDirect: { roomName: 'support', pin: '1234' } }, trunkIds: ['ST_x'], name: 'd1' } });
+      const individual = await h({ service: 'SIP', method: 'CreateSIPDispatchRule', b: { rule: { dispatchRuleIndividual: { roomPrefix: 'call-' } } } });
+      const noRoom = await h({ service: 'SIP', method: 'CreateSIPDispatchRule', b: { rule: { dispatchRuleDirect: { pin: '1' } } } });
+      const noRule = await h({ service: 'SIP', method: 'CreateSIPDispatchRule', b: {} });
+      const listed = await h({ service: 'SIP', method: 'ListSIPDispatchRule', b: {} });
+      const byTrunk = await h({ service: 'SIP', method: 'ListSIPDispatchRule', b: { trunkIds: ['ST_x'] } });
+      const deleted = await h({ service: 'SIP', method: 'DeleteSIPDispatchRule', b: { sipDispatchRuleId: (direct.body as Body).sipDispatchRuleId } });
+      const afterDelete = await h({ service: 'SIP', method: 'ListSIPDispatchRule', b: {} });
+      const deleteMissing = await h({ service: 'SIP', method: 'DeleteSIPDispatchRule', b: { sipDispatchRuleId: 'SDR_nope' } });
+      return direct.status === 200 && (direct.body as Body).rule?.dispatchRuleDirect?.roomName === 'support'
+        && individual.status === 200 && (individual.body as Body).rule?.dispatchRuleIndividual?.roomPrefix === 'call-'
+        && noRoom.status === 400 && noRule.status === 400 && (listed.body as Body).items?.length === 2
+        // byTrunk matches the rule scoped to ST_x AND the wildcard (no-trunk) individual rule
+        && (byTrunk.body as Body).items?.length === 2
+        && deleted.status === 200 && (afterDelete.body as Body).items?.length === 1 && deleteMissing.status === 404;
+    })),
+  done('livekit.sip.participants', 'sip', 'CreateSIPParticipant dials over a known outbound trunk (adds a room participant) + TransferSIPParticipant', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const trunk = await h({ service: 'SIP', method: 'CreateSIPOutboundTrunk', b: { trunk: { name: 't', address: 'sip.p.com', numbers: ['+15550000000'] } } });
+      const trunkId = (trunk.body as Body).sipTrunkId;
+      const dialed = await h({ service: 'SIP', method: 'CreateSIPParticipant', b: { sipTrunkId: trunkId, sipCallTo: '+15551112222', roomName: 'room-call', participantIdentity: 'caller-1', sipNumber: '+15550000000' } });
+      const noRoom = await h({ service: 'SIP', method: 'CreateSIPParticipant', b: { sipTrunkId: trunkId, sipCallTo: '+15551112222' } });
+      const noNumber = await h({ service: 'SIP', method: 'CreateSIPParticipant', b: { sipTrunkId: trunkId, roomName: 'room-call' } });
+      const badTrunk = await h({ service: 'SIP', method: 'CreateSIPParticipant', b: { sipTrunkId: 'ST_missing', sipCallTo: '+1', roomName: 'room-call' } });
+      // the dialed caller appears as a room participant
+      const inRoom = await h({ method: 'GetParticipant', b: { room: 'room-call', identity: 'caller-1' } });
+      const transferred = await h({ service: 'SIP', method: 'TransferSIPParticipant', b: { roomName: 'room-call', participantIdentity: 'caller-1', transferTo: 'tel:+15559998888' } });
+      const afterTransfer = await h({ method: 'GetParticipant', b: { room: 'room-call', identity: 'caller-1' } });
+      const transferGhost = await h({ service: 'SIP', method: 'TransferSIPParticipant', b: { roomName: 'room-call', participantIdentity: 'ghost', transferTo: 'tel:+1' } });
+      return dialed.status === 200 && typeof (dialed.body as Body).sipCallId === 'string' && (dialed.body as Body).sipCallId.startsWith('SCL_')
+        && (dialed.body as Body).participantIdentity === 'caller-1'
+        && noRoom.status === 400 && noNumber.status === 400 && badTrunk.status === 404
+        && inRoom.status === 200 && (inRoom.body as Body).kind === 3
+        && transferred.status === 200 && (afterTransfer.body as Body).attributes?.['sip.transferTo'] === 'tel:+15559998888'
+        && transferGhost.status === 404;
+    })),
+  done('livekit.sip.update_trunk', 'sip', 'UpdateSIPInboundTrunk/UpdateSIPOutboundTrunk — replace overwrites whole Info; update field-merges scalars (optional) + lists (ListUpdate set/add/remove/clear)', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      // --- inbound trunk -------------------------------------------------
+      const inCreated = await h({ service: 'SIP', method: 'CreateSIPInboundTrunk', b: { trunk: { name: 'main', numbers: ['+15551230000'], allowedNumbers: ['+1*'], metadata: 'orig', authUsername: 'u', authPassword: 'p' } } });
+      const inId = (inCreated.body as Body).sipTrunkId;
+      // field-merge: rename + ListUpdate add a number + set allowedNumbers; leave authUsername/password untouched
+      const inMerged = await h({ service: 'SIP', method: 'UpdateSIPInboundTrunk', b: { sipTrunkId: inId, update: { name: 'renamed', numbers: { add: ['+15559990000'] }, allowedNumbers: { set: ['+44*'] } } } });
+      // full-replace: a complete Info wholly replaces (authUsername must be cleared since absent)
+      const inReplaced = await h({ service: 'SIP', method: 'UpdateSIPInboundTrunk', b: { sipTrunkId: inId, replace: { name: 'fresh', numbers: ['+10000000000'] } } });
+      const inAfter = await h({ service: 'SIP', method: 'ListSIPInboundTrunk', b: { trunkIds: [inId] } });
+      const inRow = (inAfter.body as Body).items?.[0] as Body;
+      const inMissing = await h({ service: 'SIP', method: 'UpdateSIPInboundTrunk', b: { sipTrunkId: 'ST_nope', update: { name: 'x' } } });
+      // --- outbound trunk ------------------------------------------------
+      const outCreated = await h({ service: 'SIP', method: 'CreateSIPOutboundTrunk', b: { trunk: { name: 'pstn', address: 'a.com', numbers: ['+15557654321'], destinationCountry: 'US' } } });
+      const outId = (outCreated.body as Body).sipTrunkId;
+      const outMerged = await h({ service: 'SIP', method: 'UpdateSIPOutboundTrunk', b: { sipTrunkId: outId, update: { address: 'b.com', numbers: { remove: ['+15557654321'], add: ['+15550001111'] } } } });
+      const outMissing = await h({ service: 'SIP', method: 'UpdateSIPOutboundTrunk', b: { sipTrunkId: 'ST_nope', replace: { address: 'x' } } });
+      return inCreated.status === 200
+        // field-merge asserted VALUES: renamed, numbers appended, allowedNumbers set-replaced, untouched scalar preserved
+        && inMerged.status === 200 && (inMerged.body as Body).name === 'renamed'
+        && Array.isArray((inMerged.body as Body).numbers) && (inMerged.body as Body).numbers.length === 2
+        && (inMerged.body as Body).numbers.includes('+15559990000')
+        && JSON.stringify((inMerged.body as Body).allowedNumbers) === JSON.stringify(['+44*'])
+        && (inMerged.body as Body).authUsername === 'u' && (inMerged.body as Body).metadata === 'orig'
+        // full-replace asserted: name fresh, numbers replaced, absent authUsername cleared
+        && inReplaced.status === 200 && (inReplaced.body as Body).name === 'fresh'
+        && JSON.stringify((inReplaced.body as Body).numbers) === JSON.stringify(['+10000000000'])
+        && (inReplaced.body as Body).authUsername === '' && (inReplaced.body as Body).metadata === ''
+        // state folded from kernel log (read-back via List)
+        && inRow?.name === 'fresh' && JSON.stringify(inRow?.numbers) === JSON.stringify(['+10000000000'])
+        // negative path: unknown id => Twirp not_found
+        && inMissing.status === 404 && (inMissing.body as Body).code === 'not_found'
+        // outbound field-merge: address overwritten, list remove+add applied
+        && outMerged.status === 200 && (outMerged.body as Body).address === 'b.com'
+        && JSON.stringify((outMerged.body as Body).numbers) === JSON.stringify(['+15550001111'])
+        && (outMerged.body as Body).destinationCountry === 'US'
+        && outMissing.status === 404;
+    })),
+  done('livekit.sip.update_dispatch_rule', 'sip', 'UpdateSIPDispatchRule — replace overwrites whole Info; update field-merges name/metadata/attributes + trunkIds (ListUpdate) + the rule oneof', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const created = await h({ service: 'SIP', method: 'CreateSIPDispatchRule', b: { rule: { dispatchRuleDirect: { roomName: 'support', pin: '1234' } }, trunkIds: ['ST_a'], name: 'd1', metadata: 'm' } });
+      const id = (created.body as Body).sipDispatchRuleId;
+      // field-merge: rename, ListUpdate add a trunk, swap the rule oneof to individual; metadata untouched
+      const merged = await h({ service: 'SIP', method: 'UpdateSIPDispatchRule', b: { sipDispatchRuleId: id, update: { name: 'd1-renamed', trunkIds: { add: ['ST_b'] }, rule: { dispatchRuleIndividual: { roomPrefix: 'call-' } } } } });
+      // full-replace: complete Info wholly replaces (metadata cleared, trunkIds reset)
+      const replaced = await h({ service: 'SIP', method: 'UpdateSIPDispatchRule', b: { sipDispatchRuleId: id, replace: { rule: { dispatchRuleDirect: { roomName: 'sales' } }, name: 'fresh' } } });
+      const after = await h({ service: 'SIP', method: 'ListSIPDispatchRule', b: { dispatchRuleIds: [id] } });
+      const row = (after.body as Body).items?.[0] as Body;
+      const badRule = await h({ service: 'SIP', method: 'UpdateSIPDispatchRule', b: { sipDispatchRuleId: id, replace: { name: 'x' } } });
+      const missing = await h({ service: 'SIP', method: 'UpdateSIPDispatchRule', b: { sipDispatchRuleId: 'SDR_nope', update: { name: 'x' } } });
+      return created.status === 200
+        && merged.status === 200 && (merged.body as Body).name === 'd1-renamed' && (merged.body as Body).metadata === 'm'
+        && JSON.stringify((merged.body as Body).trunkIds) === JSON.stringify(['ST_a', 'ST_b'])
+        && (merged.body as Body).rule?.dispatchRuleIndividual?.roomPrefix === 'call-'
+        && !(merged.body as Body).rule?.dispatchRuleDirect
+        // full-replace asserted VALUES: rule back to direct/sales, metadata cleared, trunkIds reset
+        && replaced.status === 200 && (replaced.body as Body).rule?.dispatchRuleDirect?.roomName === 'sales'
+        && (replaced.body as Body).name === 'fresh' && (replaced.body as Body).metadata === ''
+        && JSON.stringify((replaced.body as Body).trunkIds) === JSON.stringify([])
+        // state folded from kernel log
+        && row?.name === 'fresh' && row?.rule?.dispatchRuleDirect?.roomName === 'sales'
+        // negative paths: replace without a rule => invalid_argument; unknown id => not_found
+        && badRule.status === 400 && missing.status === 404 && (missing.body as Body).code === 'not_found';
+    })),
+
+  // Honestly-still-undone SIP surfaces (real Twirp methods, not yet modeled):
+  // the singular get-by-id reads. Unmodeled ops fail like the vendor (not_found
+  // Twirp error) — never faked.
+  todo('livekit.sip.get_trunk', 'sip', 'GetSIPInboundTrunk/GetSIPOutboundTrunk — fetch a single trunk by id', 'api', 'niche'),
+
+  done('livekit.agents.dispatch_create', 'agents', 'CreateDispatch records an explicit agent dispatch; room+agentName required', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'agent-room' } });
+      const created = await h({ service: 'AgentDispatchService', method: 'CreateDispatch', b: { room: 'agent-room', agentName: 'transcriber', metadata: '{"lang":"en"}' } });
+      const noRoom = await h({ service: 'AgentDispatchService', method: 'CreateDispatch', b: { agentName: 'x' } });
+      const noAgent = await h({ service: 'AgentDispatchService', method: 'CreateDispatch', b: { room: 'agent-room' } });
+      const b = created.body as Body;
+      return created.status === 200 && typeof b.id === 'string' && b.id.startsWith('AD_')
+        && b.agentName === 'transcriber' && b.room === 'agent-room' && b.metadata === '{"lang":"en"}'
+        && noRoom.status === 400 && noAgent.status === 400;
+    })),
+  done('livekit.agents.dispatch_list', 'agents', 'ListDispatch filters by room and dispatch id, excludes deleted', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const a = await h({ service: 'AgentDispatchService', method: 'CreateDispatch', b: { room: 'r1', agentName: 'a1' } });
+      await h({ service: 'AgentDispatchService', method: 'CreateDispatch', b: { room: 'r2', agentName: 'a2' } });
+      const all = await h({ service: 'AgentDispatchService', method: 'ListDispatch', b: {} });
+      const byRoom = await h({ service: 'AgentDispatchService', method: 'ListDispatch', b: { room: 'r1' } });
+      const byId = await h({ service: 'AgentDispatchService', method: 'ListDispatch', b: { room: 'r1', dispatchId: (a.body as Body).id } });
+      return (all.body as Body).agentDispatches?.length === 2 && (byRoom.body as Body).agentDispatches?.length === 1
+        && (byRoom.body as Body).agentDispatches[0].room === 'r1' && (byId.body as Body).agentDispatches?.length === 1;
+    })),
+  done('livekit.agents.dispatch_delete', 'agents', 'DeleteDispatch removes a dispatch from ListDispatch; deleting twice is not_found', 'api', 'niche', () =>
+    withRoot(async (h) => {
+      const created = await h({ service: 'AgentDispatchService', method: 'CreateDispatch', b: { room: 'del-room', agentName: 'a' } });
+      const id = (created.body as Body).id;
+      const deleted = await h({ service: 'AgentDispatchService', method: 'DeleteDispatch', b: { dispatchId: id, room: 'del-room' } });
+      const listed = await h({ service: 'AgentDispatchService', method: 'ListDispatch', b: { room: 'del-room' } });
+      const again = await h({ service: 'AgentDispatchService', method: 'DeleteDispatch', b: { dispatchId: id, room: 'del-room' } });
+      return deleted.status === 200 && (listed.body as Body).agentDispatches?.length === 0 && again.status === 404;
+    })),
+  done('livekit.tokens.access_grants', 'tokens', 'AccessToken mint+verify with full video-grant parity (round-trips and rejects forgery)', 'api', 'core', async () => {
+    // Mint a join token with rich video grants, verify it round-trips with the same grants.
+    const video = { roomJoin: true, room: 'r1', canPublish: true, canSubscribe: false, canPublishData: true, hidden: true, roomRecord: false };
+    const jwt = mintAccessToken({ apiKey: API_KEY, apiSecret: API_SECRET, identity: 'alice', name: 'Alice', nowSeconds: 1000, ttlSeconds: 3600, video, metadata: '{"x":1}' });
+    const ok = verifyAccessToken(jwt, (k) => (k === API_KEY ? API_SECRET : undefined), { nowSeconds: 1000 });
+    if (!ok.ok) return false;
+    const g = ok.grants;
+    if (g.sub !== 'alice' || g.name !== 'Alice' || g.metadata !== '{"x":1}') return false;
+    if (g.video?.roomJoin !== true || g.video?.room !== 'r1' || g.video?.canPublish !== true || g.video?.canSubscribe !== false || g.video?.hidden !== true) return false;
+    // Forged signature must fail.
+    const forged = verifyAccessToken(jwt.slice(0, -3) + 'AAA', (k) => (k === API_KEY ? API_SECRET : undefined), { nowSeconds: 1000 });
+    // Wrong secret must fail.
+    const wrongSecret = verifyAccessToken(jwt, () => 'x'.repeat(36), { nowSeconds: 1000 });
+    // Expired must fail.
+    const expired = verifyAccessToken(jwt, (k) => (k === API_KEY ? API_SECRET : undefined), { nowSeconds: 1000 + 4000 });
+    // Unknown key must fail.
+    const unknown = verifyAccessToken(jwt, () => undefined, { nowSeconds: 1000 });
+    return forged.ok === false && wrongSecret.ok === false && expired.ok === false && expired.reason === 'expired' && unknown.ok === false && unknown.reason === 'unknown_key';
+  }),
+  done('livekit.tokens.sip_grants', 'tokens', 'SIP grants are carried and verified in access tokens', 'api', 'niche', async () => {
+    const jwt = mintAccessToken({ apiKey: API_KEY, apiSecret: API_SECRET, identity: 'caller', nowSeconds: 0, ttlSeconds: 600, sip: { admin: true, call: true } });
+    const ok = verifyAccessToken(jwt, (k) => (k === API_KEY ? API_SECRET : undefined), { nowSeconds: 0 });
+    return ok.ok && ok.grants.sip?.admin === true && ok.grants.sip?.call === true;
+  }),
+  done('livekit.webhooks.receiver_verify', 'webhooks', 'Webhook signing+verification (HMAC header + body sha256) round-trips and rejects tampering', 'api', 'common', async () => {
+    const body = buildWebhookBody({ event: 'room_started', id: 'EV_1', createdAtSeconds: 100, room: { name: 'r1', sid: 'RM_1' } });
+    const header = signWebhookHeader(body, API_KEY, API_SECRET, 100);
+    const ok = verifyWebhook(body, header, API_SECRET, { nowSeconds: 100 });
+    const tamperedBody = verifyWebhook(body + ' ', header, API_SECRET, { nowSeconds: 100 });
+    const badSig = verifyWebhook(body, header.slice(0, -3) + 'AAA', API_SECRET, { nowSeconds: 100 });
+    const noHeader = verifyWebhook(body, undefined, API_SECRET, { nowSeconds: 100 });
+    return ok.ok && ok.event.event === 'room_started' && tamperedBody.ok === false && tamperedBody.reason === 'hash_mismatch'
+      && badSig.ok === false && noHeader.ok === false && noHeader.reason === 'missing_header';
+  }),
+  done('livekit.webhooks.room_events', 'webhooks', 'room_started/room_finished/participant_joined webhook bodies carry the right shape', 'api', 'common', async () => {
+    for (const event of ['room_started', 'room_finished', 'participant_joined', 'participant_left'] as const) {
+      const body = buildWebhookBody({ event, createdAtSeconds: 5, room: { name: 'r', sid: 'RM_r' }, participant: { identity: 'u' } });
+      const v = verifyWebhook(body, signWebhookHeader(body, API_KEY, API_SECRET, 5), API_SECRET, { nowSeconds: 5 });
+      if (!v.ok || v.event.event !== event || (v.event.room as Body)?.name !== 'r') return false;
+    }
+    return true;
+  }),
+  done('livekit.webhooks.egress_events', 'webhooks', 'egress_started/updated/ended webhook bodies carry egressInfo and verify', 'api', 'common', async () => {
+    for (const event of ['egress_started', 'egress_updated', 'egress_ended'] as const) {
+      const body = buildWebhookBody({ event, createdAtSeconds: 9, egressInfo: { egressId: 'EG_1', roomName: 'r', status: 1 } });
+      const v = verifyWebhook(body, signWebhookHeader(body, API_KEY, API_SECRET, 9), API_SECRET, { nowSeconds: 9 });
+      if (!v.ok || v.event.event !== event || (v.event.egressInfo as Body)?.egressId !== 'EG_1') return false;
+    }
+    return true;
+  }),
+  done('livekit.errors.auth_required', 'errors', 'Missing/invalid/expired JWT returns unauthenticated when auth is enforced', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const apiKeys = { [API_KEY]: API_SECRET };
+      const noToken = await h({ method: 'ListRooms', b: {}, apiKeys, nowSeconds: 1000 });
+      const garbage = await h({ method: 'ListRooms', b: {}, apiKeys, authToken: 'not.a.jwt', nowSeconds: 1000 });
+      const wrongKeyToken = mintAccessToken({ apiKey: 'other', apiSecret: API_SECRET, nowSeconds: 1000, ttlSeconds: 600, video: { roomList: true } });
+      const unknownKey = await h({ method: 'ListRooms', b: {}, apiKeys, authToken: wrongKeyToken, nowSeconds: 1000 });
+      const expiredToken = mintAccessToken({ apiKey: API_KEY, apiSecret: API_SECRET, nowSeconds: 1000, ttlSeconds: 10, video: { roomList: true } });
+      const expired = await h({ method: 'ListRooms', b: {}, apiKeys, authToken: expiredToken, nowSeconds: 5000 });
+      // a valid token still works (auth layer is not blanket-deny)
+      const goodToken = mintAccessToken({ apiKey: API_KEY, apiSecret: API_SECRET, nowSeconds: 1000, ttlSeconds: 600, video: { roomList: true } });
+      const good = await h({ method: 'ListRooms', b: {}, apiKeys, authToken: goodToken, nowSeconds: 1000 });
+      return noToken.status === 401 && (noToken.body as Body).code === 'unauthenticated'
+        && garbage.status === 401 && unknownKey.status === 401 && expired.status === 401 && good.status === 200;
+    })),
+  done('livekit.errors.permission_denied', 'errors', 'Valid token lacking the required grant returns permission_denied', 'api', 'common', () =>
+    withRoot(async (h) => {
+      const apiKeys = { [API_KEY]: API_SECRET };
+      // token has roomList but not roomCreate
+      const listOnly = mintAccessToken({ apiKey: API_KEY, apiSecret: API_SECRET, nowSeconds: 0, ttlSeconds: 600, video: { roomList: true } });
+      const create = await h({ method: 'CreateRoom', b: { name: 'x' }, apiKeys, authToken: listOnly, nowSeconds: 0 });
+      const list = await h({ method: 'ListRooms', b: {}, apiKeys, authToken: listOnly, nowSeconds: 0 });
+      // recorder-scoped token cannot create rooms but can start egress
+      const recorder = mintAccessToken({ apiKey: API_KEY, apiSecret: API_SECRET, nowSeconds: 0, ttlSeconds: 600, video: { roomCreate: true, roomRecord: true } });
+      await h({ method: 'CreateRoom', b: { name: 'rec' }, apiKeys, authToken: recorder, nowSeconds: 0 });
+      const egress = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'rec' }, apiKeys, authToken: recorder, nowSeconds: 0 });
+      const egressDenied = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'rec' }, apiKeys, authToken: listOnly, nowSeconds: 0 });
+      return create.status === 403 && (create.body as Body).code === 'permission_denied' && list.status === 200
+        && egress.status === 200 && egressDenied.status === 403;
+    })),
+  done('livekit.errors.quota_capacity', 'errors', 'Egress start beyond the active-egress quota returns resource_exhausted', 'api', 'common', () =>
+    withRoot(async (h) => {
+      await h({ method: 'CreateRoom', b: { name: 'q-room' } });
+      const first = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'q-room' }, maxActiveEgress: 1 });
+      const second = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'q-room' }, maxActiveEgress: 1 });
+      // stopping one frees capacity again
+      await h({ service: 'Egress', method: 'StopEgress', b: { egressId: (first.body as Body).egressId } });
+      const third = await h({ service: 'Egress', method: 'StartRoomCompositeEgress', b: { roomName: 'q-room' }, maxActiveEgress: 1 });
+      return first.status === 200 && second.status === 429 && (second.body as Body).code === 'resource_exhausted' && third.status === 200;
+    })),
+  done('livekit.connector.push_egress_stop', 'connector', 'Connector pushes pending egress stop actions idempotently', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'livekit-egress-stop-cap-'));
+    try {
+      await applyTwinWrite('livekit', {
+        operation: 'egress.stop',
+        subjectType: 'egress',
+        subjectId: 'egress_EG_push',
+        fields: { id: 'egress_EG_push', egressId: 'EG_push' },
+        occurredAt: '1970-01-01T00:00:00.000Z',
+        actor: { kind: 'system' },
+      }, root);
+      let calls = 0;
+      const pushed = await performPending(async (req) => {
+        calls++;
+        if (req.service !== 'Egress' || req.method !== 'StopEgress') return { status: 400, data: {} };
+        return { status: 200, data: { egressId: 'EG_push', status: EGRESS_STATUS.COMPLETE } };
+      }, { root });
+      const again = await performPending(async () => ({ status: 200, data: {} }), { root });
+      return pushed === 1 && calls === 1 && again === 0 && pendingActions('livekit', root).length === 0;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('livekit.connector.ingress_pull', 'connector', 'Connector pulls ingress resources through the injected client', 'connector', 'common', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'livekit-ingress-pull-cap-'));
+    try {
+      const exec = async (req: { service: string; method: string }) => {
+        if (req.service === 'Ingress' && req.method === 'ListIngress') {
+          return { status: 200, data: { items: [{ ingressId: 'IN_remote', name: 'live', roomName: 'r', inputType: INGRESS_INPUT.RTMP_INPUT, participantIdentity: 'p' }] } };
+        }
+        if (req.service === 'RoomService' && req.method === 'ListRooms') return { status: 200, data: { rooms: [] } };
+        return { status: 200, data: { items: [] } };
+      };
+      await pullLiveKitSnapshot(exec, [], { root });
+      await pullLiveKitSnapshot(exec, [], { root });
+      const rows = projectResources('livekit', root);
+      return rows.filter((r) => r.type === 'ingress' && (r as Body).ingressId === 'IN_remote').length === 1;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('livekit.connector.sip_pull', 'connector', 'Connector pulls SIP inbound/outbound trunks + dispatch rules through the injected client (idempotent)', 'connector', 'niche', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'livekit-sip-pull-cap-'));
+    try {
+      const exec = async (req: { service: string; method: string }) => {
+        if (req.service === 'SIP' && req.method === 'ListSIPInboundTrunk') return { status: 200, data: { items: [{ sipTrunkId: 'ST_in', name: 'in', numbers: ['+1'] }] } };
+        if (req.service === 'SIP' && req.method === 'ListSIPOutboundTrunk') return { status: 200, data: { items: [{ sipTrunkId: 'ST_out', name: 'out', address: 'sip.x' }] } };
+        if (req.service === 'SIP' && req.method === 'ListSIPDispatchRule') return { status: 200, data: { items: [{ sipDispatchRuleId: 'SDR_1', rule: { case: 'dispatchRuleDirect', value: { roomName: 'r' } } }] } };
+        return { status: 200, data: { items: [] } };
+      };
+      await pullLiveKitSIP(exec, { root });
+      await pullLiveKitSIP(exec, { root });
+      const rows = projectResources('livekit', root);
+      return rows.filter((r) => r.type === 'sip_inbound_trunk' && (r as Body).sipTrunkId === 'ST_in').length === 1
+        && rows.filter((r) => r.type === 'sip_outbound_trunk' && (r as Body).sipTrunkId === 'ST_out').length === 1
+        && rows.filter((r) => r.type === 'sip_dispatch_rule' && (r as Body).sipDispatchRuleId === 'SDR_1').length === 1;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+  done('livekit.connector.agent_pull', 'connector', 'Connector pulls agent dispatch resources per-room through the injected client (idempotent)', 'connector', 'niche', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'livekit-agent-pull-cap-'));
+    try {
+      const exec = async (req: { service: string; method: string }) => {
+        if (req.service === 'AgentDispatchService' && req.method === 'ListDispatch') {
+          return { status: 200, data: { agentDispatches: [{ id: 'AD_remote', agentName: 'a', room: 'remote-room', metadata: '', state: { createdAt: '5' } }] } };
+        }
+        return { status: 200, data: { agentDispatches: [] } };
+      };
+      await pullLiveKitAgentDispatch(exec, ['remote-room'], { root });
+      await pullLiveKitAgentDispatch(exec, ['remote-room'], { root });
+      const rows = projectResources('livekit', root);
+      return rows.filter((r) => r.type === 'agent_dispatch' && (r as Body).dispatchId === 'AD_remote').length === 1;
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }),
+];
+
+export async function livekitCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('livekit', LIVEKIT_CAPABILITIES);
+}