@volter/twin-livekit 0.1.0

package/dist/src/livekit-budget.js

@@ -0,0 +1,131 @@
+// 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, } 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,
+};
+/**
+ * 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 = {
+    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, method) {
+    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 = {}) {
+    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 });
+}
+/**
+ * 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 = {}) {
+        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';

package/dist/src/livekit-capabilities.d.ts

@@ -0,0 +1,3 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const LIVEKIT_CAPABILITIES: CapabilitySpec[];
+export declare function livekitCapabilities(): Promise<CapabilityReport>;