@volter/twin-livekit 0.1.0

package/dist/test-fixtures/protobufs/livekit_token_source.proto

@@ -0,0 +1,49 @@
+// Copyright 2025 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package livekit;
+option go_package = "github.com/livekit/protocol/livekit";
+option csharp_namespace = "LiveKit.Proto";
+option ruby_package = "LiveKit::Proto";
+
+import "livekit_room.proto";
+
+message TokenSourceRequest {
+  // The name of the room being requested when generating credentials
+  optional string room_name = 1;
+
+  // The name of the participant being requested for this client when generating credentials
+  optional string participant_name = 2;
+
+  // The identity of the participant being requested for this client when generating credentials
+  optional string participant_identity = 3;
+
+  // Any participant metadata being included along with the credentials generation operation
+  optional string participant_metadata = 4;
+
+  // Any participant attributes being included along with the credentials generation operation
+  map<string, string> participant_attributes = 5;
+
+  // A RoomConfiguration object can be passed to request extra parameters should be included when
+  // generating connection credentials - dispatching agents, defining egress settings, etc
+  // More info: https://docs.livekit.io/home/get-started/authentication/#room-configuration
+  optional RoomConfiguration room_config = 6;
+}
+
+message TokenSourceResponse {
+  string server_url = 1;
+  string participant_token = 2;
+}

package/dist/test-fixtures/protobufs/livekit_webhook.proto

@@ -0,0 +1,62 @@
+// Copyright 2023 LiveKit, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package livekit;
+option go_package = "github.com/livekit/protocol/livekit";
+option csharp_namespace = "LiveKit.Proto";
+option ruby_package = "LiveKit::Proto";
+
+import "livekit_models.proto";
+import "livekit_egress.proto";
+import "livekit_ingress.proto";
+import "livekit_agent.proto";
+
+message WebhookEvent {
+  // one of room_started, room_finished, participant_joined, participant_left, participant_connection_aborted,
+  // track_published, track_unpublished, egress_started, egress_updated, egress_ended,
+  // ingress_started, ingress_ended, agent_job_started, agent_job_ended
+  string event = 1;
+
+  Room room = 2;
+
+  // set when event is participant_* or track_*
+  ParticipantInfo participant = 3;
+
+  // set when event is egress_*
+  EgressInfo egress_info = 9;
+
+  // set when event is ingress_*
+  IngressInfo ingress_info = 10;
+
+  // set when event is track_*
+  TrackInfo track = 8;
+
+  // set when event is agent_job_*
+  Job job = 12;
+
+  // unique event uuid
+  string id = 6;
+
+  // timestamp in seconds
+  int64 created_at = 7;
+
+  int32 num_dropped = 11 [deprecated=true];
+
+  // set when event is room_finished
+  RoomEndReason room_end_reason = 13;
+
+  // NEXT_ID: 14
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@volter/twin-livekit",
+  "version": "0.1.0",
+  "description": "Local LiveKit control-plane twin built on @volter/world-core.",
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "files": [
+    "src",
+    "client",
+    "test-fixtures",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.test.tsx",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/twin.git",
+    "directory": "packages/twin/livekit"
+  },
+  "homepage": "https://github.com/volter-ai/twin/tree/main/packages/twin/livekit#readme",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "bin": {
+    "world-livekit": "dist/src/cli.js",
+    "world-livekit-redis": "dist/src/redis-service-cli.js",
+    "world-livekit-server": "dist/src/livekit-service-cli.js",
+    "world-livekit-egress": "dist/src/egress-service-cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../../scripts/publish/build.mjs",
+    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "peerDependencies": {
+    "@volter/world-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@livekit/protocol": "^1.49.0",
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@volter/world-core": "2.0.0",
+    "@volter/world-tooling": "0.1.0",
+    "livekit-server-sdk": "^2.15.0",
+    "typescript": "^5.9.0"
+  },
+  "engines": {
+    "node": ">=22.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { hasFlag, optionValue } from '@volter/world-core/args';
+import { createLiveKitTwinServer } from './livekit-server.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const port = Number(optionValue(rest, '--port', '0')) || undefined;
+const root = optionValue(rest, '--root') || undefined;
+const readOnly = hasFlag(rest, '--read-only');
+
+if (cmd === 'serve') {
+  const server = await createLiveKitTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
+  process.stdout.write(`livekit twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${server.port}\n`);
+  await keepProcessAlive();
+} else if (cmd === 'conformance') {
+  const { checkLiveKitConformance } = await import('./livekit-conformance.ts');
+  const report = await checkLiveKitConformance({ ...(root ? { root } : {}) });
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!report.ok) process.exitCode = 1;
+} else {
+  process.stdout.write('Usage: world-livekit serve|conformance [--port N] [--root DIR] [--read-only]\n');
+}

package/src/egress-service-cli.ts

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// @ts-nocheck
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+const PORT = process.env.PORT;
+const LIVEKIT_URL = process.env.LIVEKIT_URL;
+const REDIS_HOST = process.env.REDIS_HOST;
+if (!PORT) throw new Error('PORT is required');
+if (!LIVEKIT_URL) throw new Error('LIVEKIT_URL is required');
+if (!REDIS_HOST) throw new Error('REDIS_HOST is required');
+
+// Loopback mode (EGRESS_LOOPBACK_PORTS, extra host ports such as an S3 twin's): a forwarding sidecar owns the
+// egress's network namespace and carries 127.0.0.1:<port> to this host's loopback, so the egress reaches LiveKit,
+// Redis and every named port at the same 127.0.0.1 address as everything else on this host. One storage endpoint
+// URL then means the same place to the egress (which uploads to it) and to the host process that reads it back.
+const loopbackPorts = (process.env.EGRESS_LOOPBACK_PORTS ?? '').split(',').map((p) => p.trim()).filter(Boolean);
+const loopback = loopbackPorts.length > 0;
+const portOf = (value) => /:(\d+)/.exec(value ?? '')?.[1];
+const hostLiveKitUrl = loopback ? LIVEKIT_URL : LIVEKIT_URL.replace('127.0.0.1', 'host.docker.internal');
+const hostRedis = loopback ? REDIS_HOST : REDIS_HOST.replace('127.0.0.1', 'host.docker.internal');
+const dockerReachable = (value) => value?.replace('127.0.0.1', 'host.docker.internal').replace('localhost', 'host.docker.internal');
+const proxyUrl = dockerReachable(process.env.HTTPS_PROXY || process.env.HTTP_PROXY || '');
+const caBundle = process.env.AWS_CA_BUNDLE || process.env.SSL_CERT_FILE || '';
+const containerCa = '/tmp/volter-world-ca.pem';
+const configBody = [
+  // The keys of the LiveKit this egress serves (a World names its own); the dev pair is LiveKit's --dev default.
+  `api_key: ${process.env.LIVEKIT_API_KEY ?? 'devkey'}`,
+  `api_secret: ${process.env.LIVEKIT_API_SECRET ?? 'secret'}`,
+  `ws_url: ${hostLiveKitUrl}`,
+  'insecure: true',
+  `health_port: ${PORT}`,
+  'redis:',
+  `  address: ${hostRedis}`,
+  'cpu_cost:',
+  '  room_composite_cpu_cost: 1.0',
+  '  web_cpu_cost: 1.0',
+  '  track_composite_cpu_cost: 1.0',
+  '  track_cpu_cost: 0.5',
+  'log_level: info',
+  '',
+].join('\n');
+
+const name = `volter-livekit-egress-${PORT}`;
+const sidecar = `${name}-loopback`;
+if (loopback) {
+  const forward = [...new Set([portOf(LIVEKIT_URL), portOf(REDIS_HOST), ...loopbackPorts].filter(Boolean))];
+  const script = forward.map((p) => `socat TCP-LISTEN:${p},fork,reuseaddr,bind=127.0.0.1 TCP:host.docker.internal:${p} &`).join(' ') + ' wait';
+  spawnSync('docker', ['rm', '-f', sidecar], { stdio: 'ignore' });
+  const started = spawnSync('docker', ['run', '-d', '--rm', '--name', sidecar, '-p', `127.0.0.1:${PORT}:${PORT}`, '--entrypoint', 'sh', 'alpine/socat', '-c', script], { stdio: 'inherit' });
+  if (started.status !== 0) throw new Error('the egress loopback sidecar did not start');
+}
+const dockerArgs = [
+  'run',
+  '--rm',
+  '--name',
+  name,
+  '--cap-add=SYS_ADMIN',
+  ...(loopback ? ['--network', `container:${sidecar}`] : ['-p', `127.0.0.1:${PORT}:${PORT}`]),
+  '-e',
+  `EGRESS_CONFIG_BODY=${configBody}`,
+];
+
+if (proxyUrl) {
+  const noProxy = '127.0.0.1,localhost,host.docker.internal';
+  dockerArgs.push(
+    '-e', `HTTPS_PROXY=${proxyUrl}`,
+    '-e', `HTTP_PROXY=${proxyUrl}`,
+    '-e', `https_proxy=${proxyUrl}`,
+    '-e', `http_proxy=${proxyUrl}`,
+    '-e', `NO_PROXY=${noProxy}`,
+    '-e', `no_proxy=${noProxy}`,
+  );
+}
+if (caBundle) {
+  if (!existsSync(caBundle)) throw new Error(`world CA bundle does not exist: ${caBundle}`);
+  dockerArgs.push(
+    '-e', `AWS_CA_BUNDLE=${containerCa}`,
+    '-e', `SSL_CERT_FILE=${containerCa}`,
+  );
+}
+
+dockerArgs.push('livekit/egress:latest');
+
+const child = spawn('docker', dockerArgs, { stdio: 'inherit' });
+
+function copyCaIntoContainer(attempt = 0) {
+  if (!caBundle) return;
+  const result = spawnSync('docker', ['cp', caBundle, `${name}:${containerCa}`], { stdio: 'ignore' });
+  if (result.status === 0) return;
+  if (attempt >= 50) {
+    process.stderr.write(`failed to copy world CA into ${name}; S3 egress TLS may fail\n`);
+    return;
+  }
+  setTimeout(() => copyCaIntoContainer(attempt + 1), 100);
+}
+copyCaIntoContainer();
+
+async function stop() {
+  try {
+    spawn('docker', ['rm', '-f', name], { stdio: 'ignore' });
+    if (loopback) spawn('docker', ['rm', '-f', sidecar], { stdio: 'ignore' });
+  } catch {
+    // best effort
+  }
+}
+
+process.on('SIGTERM', () => { stop(); process.exit(0); });
+process.on('SIGINT', () => { stop(); process.exit(0); });
+
+child.on('exit', (code) => { if (loopback) spawnSync('docker', ['rm', '-f', sidecar], { stdio: 'ignore' }); process.exit(code ?? 0); });

package/src/index.ts

@@ -0,0 +1,103 @@
+export { handleLiveKitTwinRequest } from './livekit-twin.ts';
+export { createLiveKitTwinFetch, createLiveKitTwinServer, type LiveKitTwinFetchOptions } from './livekit-server.ts';
+export {
+  liveKitHttpOrigin,
+  liveKitRequestForAction,
+  liveKitTwirpPath,
+  liveLiveKitExecute,
+  pullLiveKitSnapshot,
+  pullLiveKitSIP,
+  pullLiveKitAgentDispatch,
+  pushLiveKitAction,
+  syncLiveKitFromReal,
+} from './livekit-connector.ts';
+export type { LiveKitExecute, LiveKitService } from './livekit-connector.ts';
+// The client-side rate budget — the fail-closed backstop `liveLiveKitExecute` routes every live
+// request through. The mechanism is the kernel's (`@volter/world-core` -> rateBudget.ts); these are this
+// vendor's numbers and the typed bindings around them.
+export {
+  LIVEKIT_BUDGET_CEILING,
+  LIVEKIT_BUDGET_MAX_RETRY_AFTER_S,
+  LIVEKIT_BUDGET_WINDOW_MS,
+  LIVEKIT_CALL_WEIGHTS,
+  LIVEKIT_RATE_BUDGET,
+  LiveKitBudget,
+  LiveKitBudgetError,
+  liveKitBudgetPath,
+  liveKitCallWeight,
+} from './livekit-budget.ts';
+export type {
+  LiveKitBudgetErrorKind,
+  LiveKitBudgetOptions,
+  LiveKitBudgetReservation,
+  LiveKitBudgetSnapshot,
+} from './livekit-budget.ts';
+export { mintAccessToken, verifyAccessToken } from './livekit-token.ts';
+export type { LiveKitClaimGrants, LiveKitVideoGrant, LiveKitSIPGrant, MintTokenInput, VerifyResult } from './livekit-token.ts';
+export { buildWebhookBody, signWebhookHeader, verifyWebhook } from './livekit-webhook.ts';
+export type { WebhookEventInput, WebhookVerifyResult } from './livekit-webhook.ts';
+export type {
+  EgressRequestCase,
+  LiveKitEgress,
+  LiveKitIngress,
+  LiveKitParticipant,
+  LiveKitParticipantPermission,
+  LiveKitRequest,
+  LiveKitResponse,
+  LiveKitRoom,
+  LiveKitTrack,
+  LiveKitWebhookEvent,
+  LiveKitSIPInboundTrunk,
+  LiveKitSIPOutboundTrunk,
+  LiveKitSIPDispatchRule,
+  LiveKitSIPParticipant,
+  LiveKitAgentDispatch,
+} from './livekit-types.ts';
+export { EGRESS_STATUS, INGRESS_INPUT, INGRESS_STATUS, PARTICIPANT_STATE, SIP_TRANSPORT, TRACK_SOURCE, TRACK_TYPE } from './livekit-data.ts';
+
+import { registerPack, type TwinPack } from '@volter/world-core';
+import { LIVEKIT_RATE_BUDGET as RATE_BUDGET } from './livekit-budget.ts';
+
+import { performLiveKitAction, syncLiveKitFromRemote } from './livekit-connector.ts';
+
+export const pack: TwinPack = {
+  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
+  // state system: perform one entry against LiveKit's Twirp RPCs, refresh the root from them. Moved
+  // 2026-09-08.
+  protocol: '2',
+  refresh: { every: '1m', webhook: true, onDemand: { atMost: '10s' } }, // rooms and egresses move fast
+  stateSystem: { perform: performLiveKitAction, refresh: syncLiveKitFromRemote },
+  // the round trip: create a room — LiveKit's CreateRoom answers the existing room when it is already
+  // there, so it repeats cleanly on a branch
+  roundTrip: { method: 'POST', path: '/twirp/livekit.RoomService/CreateRoom', body: { name: 'round-trip' } },
+  parityOrigin: 'http://twin',
+  vendor: 'livekit',
+  // The SAME object livekit-budget.ts declares at module load — one source of truth, so registering
+  // the pack and importing the connector arm identical numbers.
+  rateBudget: RATE_BUDGET,
+  transport: 'rest',
+  archetype: 'crud',
+  bin: 'world-livekit',
+  resources: ['room', 'participant', 'egress', 'ingress', 'sip_inbound_trunk', 'sip_outbound_trunk', 'sip_dispatch_rule', 'sip_participant', 'agent_dispatch'],
+  specSource: 'LiveKit Server APIs: RoomService (incl. Forward/MoveParticipant), Egress, Ingress, SIP (SIPService), and AgentDispatchService Twirp JSON endpoints + AccessToken/WebhookReceiver schemes used by livekit-server-sdk 2.15.x; this pack models the control plane, not the media plane.',
+  description: 'LiveKit control-plane twin — local rooms, participants, egress/ingress lifecycle, access-token grants, and webhook signing for server SDK integrations.',
+  browserRouting: { apiPathPrefix: '/twirp/', loaderHost: 'https://livekit.cloud' },
+  // INTERCEPTION RULING — hostsNone, the pack's own home for it: real local media plane
+  // (livekit-server) exposed via app-read env (LIVEKIT_URL is ws:// — WebSocket media is
+  // outside the HTTP injector's reach).
+  hostsNone:
+    "real local media plane (livekit-server) exposed via app-read env (LIVEKIT_URL is ws:// — WebSocket media is outside the HTTP injector's reach)",
+  // Adoption, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
+  // 2026-08-31).
+  adoption: {
+    // LiveKit's official Python distributions: the server API client (the counterpart of
+    // `livekit-server-sdk`), the realtime SDK (`@livekit/rtc-node`), and the agents framework whose
+    // core connects to a LiveKit server.
+    pypi: ['livekit-api', 'livekit', 'livekit-agents'],
+    sdks: ['livekit-server-sdk', '@livekit/rtc-node'],
+    scopes: ['@livekit/'],
+    envStems: ['LIVEKIT'],
+  },
+};
+// registered at import: the kernel learns the pack's state system (protocol 2)
+registerPack(pack);

package/src/livekit-budget.ts

@@ -0,0 +1,158 @@
+// LiveKit's CLIENT-SIDE RATE BUDGET — the pack's DECLARATION (the numbers) plus the thin typed
+// bindings `liveLiveKitExecute` uses. The MECHANISM — the durable token-keyed ledger, the rolling
+// window, reserve-under-lock, the `Retry-After`/429 cooldown, fail-CLOSED on a corrupt ledger — lives
+// ONCE in the vendor-agnostic kernel (`@volter/world-core` → `rateBudget.ts`). Read that module's header
+// for the full rationale AND for the honest list of what the guard does not guarantee (an injected
+// clock or ledger path still defeats it — it guards carelessness, not malice).
+//
+// ── WHY THIS EXISTS: THE MISSING CHOKE POINT ─────────────────────────────────────────────────
+// A ~4.5-day Figma token lockout (2026-07-25) came from a burst of raw vendor calls made OUTSIDE any
+// guarded client. The lesson generalized: a pack with no single construction site for its live client
+// is a pack that CANNOT be protected, because there is nowhere for a guard to sit.
+//
+// This connector took an INJECTED `LiveKitExecute` and nothing more. Excellent for testing — every
+// verify runs offline against a fake — but it meant the pack never built a network-calling execute, so
+// a rate budget could only ever be something the CALLER opted into. `liveLiveKitExecute` (in
+// `livekit-connector.ts`) is the choke point that fixes that: the ONE place in this pack that turns a
+// key/secret pair into a function that really talks to a LiveKit server, with this budget charged
+// BEFORE every request goes out. The injected-function contract is untouched.
+//
+// ── WHY THE FAN-OUT SHAPE MATTERS HERE ───────────────────────────────────────────────────────
+// `collectLiveKitSnapshot` lists rooms and then, FOR EACH ROOM, lists that room's participants; the
+// agent-dispatch collector likewise issues one `ListDispatch` per room. So one innocent-looking
+// `syncLiveKitFromReal` over a busy project emits O(rooms) Server-API requests as fast as the event
+// loop allows. That is exactly the shape a budget exists to bound.
+//
+// ── HOW THE CEILING WAS CHOSEN ───────────────────────────────────────────────────────────────
+// LiveKit publishes a scalar for precisely this surface: "All projects have a Server API rate limit of
+// 1,000 requests per minute" — applying to RoomService/EgressService-style requests, NOT to SDK
+// operations like joining a room or sending data packets (docs.livekit.io/deploy/admin/quotas-and-limits/;
+// Scale-plan customers may request an increase). Every call this connector makes is a Server API call.
+//
+// So: 200 weighted units per 60s. With the cheap list/get reads priced at 1 that is 200 requests a
+// minute — 20% of the documented limit — which comfortably covers a real snapshot (a project with a
+// few dozen rooms) while a runaway per-room loop is refused rather than allowed to consume the whole
+// project-wide allowance that the app's OWN server also depends on.
+//
+// ── HOW THE WEIGHTS WERE CHOSEN ──────────────────────────────────────────────────────────────
+// LiveKit counts REQUESTS, so weight 1 is the faithful price for a read, and the flat list/get calls
+// get it. Two get 2 — `RoomService/ListParticipants` and `AgentDispatchService/ListDispatch` — not
+// because LiveKit charges more (it does not) but because they are the two whose call count is
+// UNBOUNDED IN THE ROOM COUNT: they are the inner loop above. Doubling their price halves the room
+// count at which a runaway walk is stopped while barely touching a small snapshot. A judgement call,
+// not a published cost.
+//
+// Everything unclassified costs `defaultWeight` (2) — above a read, because a mutating Twirp method
+// (StartEgress, CreateIngress, SendData) is not a list read and this pack has read no published
+// per-method figure for it. Nothing is ever free.
+import {
+  declareRateBudget,
+  rateBudgetPath,
+  rateBudgetWeight,
+  RateBudget,
+  type RateBudgetDeclaration,
+  type RateBudgetOptions,
+  type RateBudgetReservation,
+  type RateBudgetSnapshot,
+} from '@volter/world-core';
+
+const VENDOR = 'livekit';
+
+/** Rolling window, in ms. Matches LiveKit's own per-MINUTE Server API limit. */
+export const LIVEKIT_BUDGET_WINDOW_MS = 60_000;
+
+/** Weighted units allowed inside one window. 200 reads/60s = 20% of the documented 1,000/min. */
+export const LIVEKIT_BUDGET_CEILING = 200;
+
+/** Seconds. A `Retry-After` above this means the project is throttled hard — fail loudly. */
+export const LIVEKIT_BUDGET_MAX_RETRY_AFTER_S = 300;
+
+/**
+ * Per-call cost, keyed by the Twirp RPC id (`"<Service>/<Method>"`) this connector is about to invoke.
+ * A LiveKit call is not a REST path — it is an RPC — so the RPC id is the honest call key.
+ */
+export const LIVEKIT_CALL_WEIGHTS = {
+  /** The per-room inner loop: one `ListParticipants` / `ListDispatch` per room. Unbounded fan-out. */
+  perRoomFanOut: 2,
+  /** A flat `List…` / `Get…` read: one call for a whole collection. */
+  read: 1,
+  /** Anything else, including every mutating method. Priced above a read, never free. */
+  other: 2,
+} as const;
+
+/**
+ * THE PACK'S DECLARATION — pure data, the only LiveKit-specific thing in the whole budget. Rules are
+ * ordered and first-match-wins, and they are keyed on the Twirp RPC id, so the per-room fan-out rules
+ * must come BEFORE the generic list/get rule.
+ *
+ * Also exported as `pack.rateBudget` (see index.ts), so `registerPack` arms it too.
+ */
+export const LIVEKIT_RATE_BUDGET: RateBudgetDeclaration = {
+  windowMs: LIVEKIT_BUDGET_WINDOW_MS,
+  ceiling: LIVEKIT_BUDGET_CEILING,
+  defaultWeight: LIVEKIT_CALL_WEIGHTS.other,
+  maxRetryAfterSeconds: LIVEKIT_BUDGET_MAX_RETRY_AFTER_S,
+  rules: [
+    { match: '^RoomService/ListParticipants$', weight: LIVEKIT_CALL_WEIGHTS.perRoomFanOut },
+    { match: '^AgentDispatchService/ListDispatch$', weight: LIVEKIT_CALL_WEIGHTS.perRoomFanOut },
+    { match: '^[A-Za-z]+/(List|Get)[A-Za-z]*$', weight: LIVEKIT_CALL_WEIGHTS.read },
+  ],
+  reason:
+    'LiveKit documents that "All projects have a Server API rate limit of 1,000 requests per minute" — ' +
+    'covering RoomService/Egress/Ingress/SIP-style requests, not SDK room operations ' +
+    '(docs.livekit.io/deploy/admin/quotas-and-limits/). Every call this connector makes is a Server API ' +
+    'call. 200 weighted units / 60s prices a flat list/get at 1, so the ceiling is 20% of that ' +
+    'project-wide limit — which the app\'s own server shares. ListParticipants and ListDispatch cost 2 ' +
+    'because the snapshot issues one PER ROOM, so their call count is unbounded in the room count — ' +
+    'a judgement call, not a published cost.',
+};
+
+// Declared at module load, so merely importing this module (which `livekit-connector.ts` does) is
+// enough to arm the real ceiling. A budget constructed BEFORE this runs falls back to the kernel's
+// DEFAULT_RATE_BUDGET, which is tighter in call count but prices every call at 2 — cheaper than
+// nothing here, yet it also prices a cheap read at 2, so the two are not ordered. `RateBudget` reads
+// its policy live precisely so this declaration takes effect the moment it lands, and constructing
+// through the subclass below (which imports this module) makes the ordering a non-issue in practice.
+declareRateBudget(VENDOR, LIVEKIT_RATE_BUDGET);
+
+/**
+ * Price one call. Keyed off the Twirp RPC the connector is ABOUT to invoke, so an unclassified method
+ * still costs `defaultWeight` — an unknown method must never be free.
+ */
+export function liveKitCallWeight(service: string, method: string): number {
+  return rateBudgetWeight(VENDOR, `${service}/${method}`);
+}
+
+/** Where LiveKit's ledger lives. API-key-keyed and cwd-independent by default (the limit is per
+ *  PROJECT and the API key identifies the project, so a cwd-scoped ledger would hand the same project
+ *  a fresh allowance in every checkout, worktree and CI matrix leg); pass `root` to opt into
+ *  world-scoped accounting instead. */
+export function liveKitBudgetPath(opts: { root?: string; token?: string } | string = {}): string {
+  const o = typeof opts === 'string' ? { root: opts } : opts;
+  // VENDOR spread LAST: a loosely-typed `{ vendor: 'other', … }` slipping through (TypeScript's
+  // excess-property check only catches object literals) must not redirect this pack's ledger to
+  // another vendor's file.
+  return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+
+/** Construction options for LiveKit's budget. The vendor is fixed; everything else may only TIGHTEN. */
+export type LiveKitBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+
+/**
+ * LiveKit's budget — the shared kernel guard bound to this vendor's declaration. A real subclass, not
+ * an alias, so `budget instanceof LiveKitBudget` in `liveLiveKitExecute` still means "a budget that
+ * accounts against LIVEKIT's ledger under LIVEKIT's ceiling": another vendor's `RateBudget` (with its
+ * own, possibly larger, ceiling) is NOT assignable there.
+ */
+export class LiveKitBudget extends RateBudget {
+  constructor(opts: LiveKitBudgetOptions = {}) {
+    super({ ...opts, vendor: VENDOR });
+  }
+}
+
+/** The typed refusal. One error class shared with every other vendor's budget; `err.vendor` says
+ *  which one refused, and `err.kind` says why. */
+export { RateBudgetError as LiveKitBudgetError } from '@volter/world-core';
+export type { RateBudgetErrorKind as LiveKitBudgetErrorKind } from '@volter/world-core';
+export type LiveKitBudgetReservation = RateBudgetReservation;
+export type LiveKitBudgetSnapshot = RateBudgetSnapshot;