@clipwright/core 0.1.0 → 0.3.0

package/dist/rate-limit.d.ts

@@ -0,0 +1,160 @@
+import { z } from "zod";
+/**
+ * RATE LIMIT — ФОРМА ОТВЕТА И ИМЕНА ЗАГОЛОВКОВ, ОДНИМ ДОМОМ (US-605).
+ *
+ * `spec.md` и `docs/03-api.md` объявляли «60 rpm, заголовки
+ * `X-RateLimit-Remaining`/`X-RateLimit-Reset`, код `rate_limited` 429» — и в
+ * коде не было ничего. Строить это тремя литералами в трёх пакетах значило бы
+ * воспроизвести ровно тот разрыв между объявлением и реализацией, ради
+ * закрытия которого стори и заведена: имя заголовка, разъехавшееся между
+ * сервером и клиентом, не ловится ни компилятором, ни тестом одной стороны.
+ *
+ * Поэтому здесь лежат И схема тела, И имена заголовков, И числа лимитов.
+ * REST, SDK и MCP берут их отсюда; тест `rate-limit.contract.test.ts` в
+ * `apps/api` проверяет, что литерала `rate_limited` нет ни в одной из трёх
+ * поверхностей (правило проекта №2, блокер 9 внешнего ревью плана).
+ */
+/** Имя заголовка с потолком ведра — сколько запросов в окне разрешено всего. */
+export declare const RATE_LIMIT_LIMIT_HEADER = "X-RateLimit-Limit";
+/** Сколько запросов в текущем окне ещё осталось. Ноль — законное значение. */
+export declare const RATE_LIMIT_REMAINING_HEADER = "X-RateLimit-Remaining";
+/**
+ * Через сколько СЕКУНД остаток вырастет хотя бы на единицу.
+ *
+ * ЕДИНИЦА — ДЕЛЬТА, А НЕ UNIX-ВРЕМЯ, и это осознанное расхождение с GitHub.
+ * Дельта не зависит от часов клиента: агент на машине с уехавшим временем,
+ * вычитая epoch из своего `Date.now()`, ждал бы неверно и упирался бы в лимит
+ * повторно. Направление то же, что у черновика IETF (`RateLimit-Reset`), и то
+ * же, что у `Retry-After` ниже — две единицы в одном ответе путали бы сильнее,
+ * чем расхождение с чужой реализацией.
+ *
+ * СМЫСЛ ИМЕННО «ВЫРАСТЕТ НА ЕДИНИЦУ», а не «обнулится счётчик»: окно
+ * скользящее, и полного обнуления в нём не происходит — запросы выпадают из
+ * окна по одному. Для отказа это ровно момент, когда можно повторить.
+ */
+export declare const RATE_LIMIT_RESET_HEADER = "X-RateLimit-Reset";
+/** Стандартный `Retry-After` (RFC 9110), в секундах. Только на 429. */
+export declare const RETRY_AFTER_HEADER = "Retry-After";
+/** Длина окна. Одна для обоих вёдер: «в минуту» — то, что объявлено. */
+export declare const RATE_LIMIT_WINDOW_SECONDS = 60;
+/**
+ * ПЛАТНОЕ ВЕДРО — 60 запросов в минуту. Число не выбрано здесь, а взято из
+ * объявления (`spec.md`, `docs/03-api.md`): стори закрывает разрыв «объявлено,
+ * но не построено», и менять заодно само объявление значило бы закрыть его
+ * подгонкой.
+ */
+export declare const RATE_LIMIT_PAID_PER_MINUTE = 60;
+/**
+ * БЕСПЛАТНОЕ ВЕДРО — 300 запросов в минуту, отдельным счётчиком.
+ *
+ * ПОЧЕМУ ОТДЕЛЬНО. Общее ведро с платным путём отравило бы ШТАТНЫЙ агентный
+ * цикл: по ADR-009 клиент поллит `GET /v1/runs/:id` каждые ~5 с, то есть 12
+ * запросов в минуту НА РАН. При потолке в три параллельных рана (та же стори)
+ * один только поллинг съедает 36 из 60, и агент упирался бы в лимит, ничего не
+ * заказывая — отказ там, где нет ни траты, ни нагрузки на вендора.
+ *
+ * ОТКУДА 300. Пол — те самые 36 плюс `quote` перед каждым запуском и редкий
+ * `voices`: около 40 в минуту на аккаунт, работающий на полном потолке
+ * параллельности. 300 даёт запас в 7.5 раза (место для ретраев, нескольких
+ * агентов на одном аккаунте и более частого поллинга), но остаётся ПОТОЛКОМ:
+ * зациклившийся клиент упирается в него на пятой секунде, а не выкачивает
+ * базу минутами. Число живёт здесь, а не в переменной окружения, потому что
+ * оно часть публичного контракта и объявлено в `docs/03-api.md`.
+ */
+export declare const RATE_LIMIT_FREE_PER_MINUTE = 300;
+/**
+ * ПОТОЛОК ОДНОВРЕМЕННЫХ РЕНДЕРОВ НА АККАУНТ — 3 (`spec.md:106`).
+ *
+ * Число живёт рядом с лимитом частоты, потому что они считают одно и то же
+ * сверху: сколько работы аккаунт может держать у нас в моменте. Из него же
+ * выведен пол бесплатного ведра (три рана × 12 опросов в минуту).
+ *
+ * ПРЕВЫШЕНИЕ СТАВИТ В ОЧЕРЕДЬ, А НЕ ОТВЕРГАЕТ. Четвёртый ран получает 202 и
+ * ждёт своей очереди; отказ здесь был бы хуже для агента, чем ожидание, —
+ * ему пришлось бы городить собственный планировщик поверх нашего.
+ *
+ * ЭТОТ ПОТОЛОК ЖИВЁТ ПОД ОБЩИМ ЛИМИТОМ ТАРИФА Trigger.dev, а не вместо него.
+ * Числа тарифа и следствие для волны N=50 — в `docs/02-architecture.md`.
+ */
+export declare const MAX_CONCURRENT_RENDERS_PER_ACCOUNT = 3;
+/**
+ * Ведро. Оно же — ось счётчика в БД и значение колонки `bucket`.
+ *
+ * Тип живёт здесь, а не в `service-core`, ровно потому, что ведро НАЗВАНО в
+ * ответе клиенту (сообщение ниже отличает платный лимит от бесплатного).
+ * Разъедься строка в счётчике со строкой в сообщении — клиент получал бы
+ * совет ждать не того окна.
+ */
+export type RateLimitScope = "paid" | "free";
+/**
+ * Тело отказа 429. Числа лежат ВНУТРИ `error` — по тому же доводу, что и у
+ * денежных отказов в `errors.ts`: у ответа об ошибке один конверт, и всё, что
+ * объясняет отказ, лежит в нём.
+ */
+export declare const rateLimitedError: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodLiteral<"rate_limited">;
+        message: z.ZodString;
+        limit: z.ZodNumber;
+        window_seconds: z.ZodNumber;
+        retry_after_seconds: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type RateLimitedError = z.infer<typeof rateLimitedError>;
+/**
+ * Сборка тела «слишком часто».
+ *
+ * Формулировка живёт ЗДЕСЬ, а не в мидлваре, по той же причине, что и форма:
+ * вёдер два, и объяснять отказ они обязаны одинаково. Сообщение НАЗЫВАЕТ
+ * ведро — иначе агент, упершийся в платный лимит, не отличит его от
+ * бесплатного и остановит поллинг уже принятых ранов.
+ */
+export declare function rateLimitedBody(args: {
+    limit: number;
+    windowSeconds: number;
+    retryAfterSeconds: number;
+    scope: RateLimitScope;
+    /**
+     * Был ли отбитый запрос АДРЕСОВАН СОЗДАНИЮ РАНА. Знает это только вызыватель:
+     * ведро само по себе не различает платный маршрут и любой неизвестный путь,
+     * который попадает туда же по безопасному дефолту.
+     *
+     * Нужен ради правдивости совета (внешнее ревью, круг 5): предупреждение
+     * «новый ключ может запустить ВТОРОЙ платный рендер» осмысленно только там,
+     * где рендер вообще бывает; на опечатке в пути или неподдержанном методе оно
+     * говорит о невозможном. По умолчанию `false` — молчим, пока не сказано
+     * обратное.
+     *
+     * ИМЯ ГОВОРИТ «АДРЕСОВАН», А НЕ «ЗАПУСТИТ», И ЭТО ТОЧНОЕ СЛОВО (круг 6).
+     * Знать, дошёл бы запрос до создания рана, мидлвара не может: битое тело,
+     * отклонённое поле, конфликт формата, опущенный килсвитч и нехватка кредитов
+     * отбиваются УЖЕ В ОБРАБОТЧИКЕ, то есть после лимита. Чтобы это выяснить,
+     * пришлось бы выполнить работу обработчика до решения о лимите — ровно ту
+     * работу, ради недопущения которой лимит и стоит впереди. Поэтому доступный
+     * факт один: «запрос шёл на платный маршрут», и обещание сформулировано в
+     * сослагательном («может»), а не в изъявительном наклонении.
+     */
+    targetsRunCreation?: boolean;
+}): RateLimitedError;
+/**
+ * Сборка тела «слишком много НЕУДАЧНЫХ ПОПЫТОК АУТЕНТИФИКАЦИИ» (US-626, круг
+ * подтверждения).
+ *
+ * ЖИВЁТ ЗДЕСЬ, А НЕ В МИДЛВАРЕ, ПО ПРАВИЛУ ПРОЕКТА №2 — и это не формальность:
+ * литерал `rate_limited`, собранный на месте, поймал сторож
+ * `rate-limit.single-source.test.ts` в тот же прогон. Форма 429 у продукта одна,
+ * потому что разбирают её клиентские пакеты одной схемой (`rateLimitedError`):
+ * тело без любого из трёх чисел не пройдёт разбор вовсе, и агент получит
+ * «неизвестный отказ» вместо «подожди столько секунд».
+ *
+ * ОТЛИЧИЕ ОТ `rateLimitedBody` — ТОЛЬКО СООБЩЕНИЕ, и различать их обязательно.
+ * Тот отказ адресован ДЕЙСТВУЮЩЕМУ клиенту и говорит про ведро аккаунта,
+ * идемпотентность и второй платный рендер. Этот приходит тому, кто предъявил
+ * НЕработающий ключ: ни аккаунта, ни рана у него нет, и совет про
+ * `Idempotency-Key` был бы разговором о невозможном.
+ */
+export declare function authThrottledBody(args: {
+    limit: number;
+    windowSeconds: number;
+    retryAfterSeconds: number;
+}): RateLimitedError;

package/dist/rate-limit.js

@@ -0,0 +1,182 @@
+import { z } from "zod";
+/**
+ * RATE LIMIT — ФОРМА ОТВЕТА И ИМЕНА ЗАГОЛОВКОВ, ОДНИМ ДОМОМ (US-605).
+ *
+ * `spec.md` и `docs/03-api.md` объявляли «60 rpm, заголовки
+ * `X-RateLimit-Remaining`/`X-RateLimit-Reset`, код `rate_limited` 429» — и в
+ * коде не было ничего. Строить это тремя литералами в трёх пакетах значило бы
+ * воспроизвести ровно тот разрыв между объявлением и реализацией, ради
+ * закрытия которого стори и заведена: имя заголовка, разъехавшееся между
+ * сервером и клиентом, не ловится ни компилятором, ни тестом одной стороны.
+ *
+ * Поэтому здесь лежат И схема тела, И имена заголовков, И числа лимитов.
+ * REST, SDK и MCP берут их отсюда; тест `rate-limit.contract.test.ts` в
+ * `apps/api` проверяет, что литерала `rate_limited` нет ни в одной из трёх
+ * поверхностей (правило проекта №2, блокер 9 внешнего ревью плана).
+ */
+/** Имя заголовка с потолком ведра — сколько запросов в окне разрешено всего. */
+export const RATE_LIMIT_LIMIT_HEADER = "X-RateLimit-Limit";
+/** Сколько запросов в текущем окне ещё осталось. Ноль — законное значение. */
+export const RATE_LIMIT_REMAINING_HEADER = "X-RateLimit-Remaining";
+/**
+ * Через сколько СЕКУНД остаток вырастет хотя бы на единицу.
+ *
+ * ЕДИНИЦА — ДЕЛЬТА, А НЕ UNIX-ВРЕМЯ, и это осознанное расхождение с GitHub.
+ * Дельта не зависит от часов клиента: агент на машине с уехавшим временем,
+ * вычитая epoch из своего `Date.now()`, ждал бы неверно и упирался бы в лимит
+ * повторно. Направление то же, что у черновика IETF (`RateLimit-Reset`), и то
+ * же, что у `Retry-After` ниже — две единицы в одном ответе путали бы сильнее,
+ * чем расхождение с чужой реализацией.
+ *
+ * СМЫСЛ ИМЕННО «ВЫРАСТЕТ НА ЕДИНИЦУ», а не «обнулится счётчик»: окно
+ * скользящее, и полного обнуления в нём не происходит — запросы выпадают из
+ * окна по одному. Для отказа это ровно момент, когда можно повторить.
+ */
+export const RATE_LIMIT_RESET_HEADER = "X-RateLimit-Reset";
+/** Стандартный `Retry-After` (RFC 9110), в секундах. Только на 429. */
+export const RETRY_AFTER_HEADER = "Retry-After";
+/** Длина окна. Одна для обоих вёдер: «в минуту» — то, что объявлено. */
+export const RATE_LIMIT_WINDOW_SECONDS = 60;
+/**
+ * ПЛАТНОЕ ВЕДРО — 60 запросов в минуту. Число не выбрано здесь, а взято из
+ * объявления (`spec.md`, `docs/03-api.md`): стори закрывает разрыв «объявлено,
+ * но не построено», и менять заодно само объявление значило бы закрыть его
+ * подгонкой.
+ */
+export const RATE_LIMIT_PAID_PER_MINUTE = 60;
+/**
+ * БЕСПЛАТНОЕ ВЕДРО — 300 запросов в минуту, отдельным счётчиком.
+ *
+ * ПОЧЕМУ ОТДЕЛЬНО. Общее ведро с платным путём отравило бы ШТАТНЫЙ агентный
+ * цикл: по ADR-009 клиент поллит `GET /v1/runs/:id` каждые ~5 с, то есть 12
+ * запросов в минуту НА РАН. При потолке в три параллельных рана (та же стори)
+ * один только поллинг съедает 36 из 60, и агент упирался бы в лимит, ничего не
+ * заказывая — отказ там, где нет ни траты, ни нагрузки на вендора.
+ *
+ * ОТКУДА 300. Пол — те самые 36 плюс `quote` перед каждым запуском и редкий
+ * `voices`: около 40 в минуту на аккаунт, работающий на полном потолке
+ * параллельности. 300 даёт запас в 7.5 раза (место для ретраев, нескольких
+ * агентов на одном аккаунте и более частого поллинга), но остаётся ПОТОЛКОМ:
+ * зациклившийся клиент упирается в него на пятой секунде, а не выкачивает
+ * базу минутами. Число живёт здесь, а не в переменной окружения, потому что
+ * оно часть публичного контракта и объявлено в `docs/03-api.md`.
+ */
+export const RATE_LIMIT_FREE_PER_MINUTE = 300;
+/**
+ * ПОТОЛОК ОДНОВРЕМЕННЫХ РЕНДЕРОВ НА АККАУНТ — 3 (`spec.md:106`).
+ *
+ * Число живёт рядом с лимитом частоты, потому что они считают одно и то же
+ * сверху: сколько работы аккаунт может держать у нас в моменте. Из него же
+ * выведен пол бесплатного ведра (три рана × 12 опросов в минуту).
+ *
+ * ПРЕВЫШЕНИЕ СТАВИТ В ОЧЕРЕДЬ, А НЕ ОТВЕРГАЕТ. Четвёртый ран получает 202 и
+ * ждёт своей очереди; отказ здесь был бы хуже для агента, чем ожидание, —
+ * ему пришлось бы городить собственный планировщик поверх нашего.
+ *
+ * ЭТОТ ПОТОЛОК ЖИВЁТ ПОД ОБЩИМ ЛИМИТОМ ТАРИФА Trigger.dev, а не вместо него.
+ * Числа тарифа и следствие для волны N=50 — в `docs/02-architecture.md`.
+ */
+export const MAX_CONCURRENT_RENDERS_PER_ACCOUNT = 3;
+/**
+ * Тело отказа 429. Числа лежат ВНУТРИ `error` — по тому же доводу, что и у
+ * денежных отказов в `errors.ts`: у ответа об ошибке один конверт, и всё, что
+ * объясняет отказ, лежит в нём.
+ */
+export const rateLimitedError = z.object({
+    error: z.object({
+        code: z.literal("rate_limited"),
+        message: z.string().min(1),
+        /** Потолок ведра, в которое попал запрос. */
+        limit: z.number().int().positive(),
+        /** Длина окна в секундах — без неё `limit` не значит ничего. */
+        window_seconds: z.number().int().positive(),
+        /** Через сколько секунд повторять. Совпадает с `Retry-After`. */
+        retry_after_seconds: z.number().int().positive(),
+    }),
+});
+/**
+ * Сборка тела «слишком часто».
+ *
+ * Формулировка живёт ЗДЕСЬ, а не в мидлваре, по той же причине, что и форма:
+ * вёдер два, и объяснять отказ они обязаны одинаково. Сообщение НАЗЫВАЕТ
+ * ведро — иначе агент, упершийся в платный лимит, не отличит его от
+ * бесплатного и остановит поллинг уже принятых ранов.
+ */
+export function rateLimitedBody(args) {
+    // ХВОСТ СООБЩЕНИЯ ЗАВИСИТ ОТ ВЕДРА, И ЭТО НЕ УКРАШЕНИЕ (внешнее ревью, круги 2 и 3).
+    //
+    // Первая редакция дописывала «no run was created» к ОБОИМ отказам, и это была
+    // ложь дважды.
+    //
+    // НА БЕСПЛАТНОМ ВЕДРЕ: агент, опрашивающий статус уже ЗАПУЩЕННОГО рана,
+    // получал бы 429 с уверением, что рана нет, — и мог бы бросить работу, за
+    // которую уже заплачено. Ту же работу защищает и решение пропускать
+    // бесплатные пути при отказе счётчика.
+    //
+    // НА ПЛАТНОМ: лимит стоит ПЕРЕД обработчиком, поэтому 429 получает и ПОВТОР
+    // с уже занятым `Idempotency-Key` — запрос, за которым ран существует. «No
+    // run was created» толкает агента взять новый ключ, а новый ключ есть второй
+    // платный рендер. Поэтому платный хвост больше ничего не утверждает о
+    // существовании рана и прямо велит повторить С ТЕМ ЖЕ ключом: это верно и
+    // для первого запроса (там повтор просто создаст ран), и для повтора.
+    // ОПИСАНИЕ ВЕДРА ТОЖЕ ОБЯЗАНО БЫТЬ ВЕРНЫМ (внешнее ревью, круг 4). В платное
+    // ведро по построению попадает не только создание рана, но и любой
+    // неизвестный путь под авторизованными префиксами — так выбран безопасный
+    // дефолт. Формулировка «starting runs» описывала бы клиенту не тот отказ.
+    const surface = args.scope === "paid"
+        ? "paid requests (starting a run, and any unrecognised authenticated path)"
+        : "free requests (quotes, voices, run status, account)";
+    // СОВЕТ ПРО КЛЮЧ ДАЁТСЯ ТОЛЬКО ТАМ, ГДЕ ОН ОСМЫСЛЕН (круги 4 и 5).
+    //
+    // Круг 4 снял безусловность: 429 получает и запрос, который ключа не
+    // присылал. Круг 5 снял вторую неточность — предупреждение о «втором платном
+    // рендере» уходило и на опечатку в пути, и на неподдержанный метод, где
+    // никакой ключ ничего не отрендерит. Теперь его печатает только запуск рана,
+    // и `targetsRunCreation` приходит от мидлвары — она единственная знает маршрут.
+    const tail = args.scope === "free"
+        ? "nothing was charged; runs already started keep going and stay retrievable."
+        : args.targetsRunCreation === true
+            ? "nothing was charged. If this request carried an Idempotency-Key, retry with the SAME key: a new key can start a second paid render."
+            : "nothing was charged.";
+    return rateLimitedError.parse({
+        error: {
+            code: "rate_limited",
+            message: `Rate limit of ${args.limit} ${surface} per ${args.windowSeconds} seconds is exhausted ` +
+                `for this account. Retry in ${args.retryAfterSeconds} seconds; ${tail}`,
+            limit: args.limit,
+            window_seconds: args.windowSeconds,
+            retry_after_seconds: args.retryAfterSeconds,
+        },
+    });
+}
+/**
+ * Сборка тела «слишком много НЕУДАЧНЫХ ПОПЫТОК АУТЕНТИФИКАЦИИ» (US-626, круг
+ * подтверждения).
+ *
+ * ЖИВЁТ ЗДЕСЬ, А НЕ В МИДЛВАРЕ, ПО ПРАВИЛУ ПРОЕКТА №2 — и это не формальность:
+ * литерал `rate_limited`, собранный на месте, поймал сторож
+ * `rate-limit.single-source.test.ts` в тот же прогон. Форма 429 у продукта одна,
+ * потому что разбирают её клиентские пакеты одной схемой (`rateLimitedError`):
+ * тело без любого из трёх чисел не пройдёт разбор вовсе, и агент получит
+ * «неизвестный отказ» вместо «подожди столько секунд».
+ *
+ * ОТЛИЧИЕ ОТ `rateLimitedBody` — ТОЛЬКО СООБЩЕНИЕ, и различать их обязательно.
+ * Тот отказ адресован ДЕЙСТВУЮЩЕМУ клиенту и говорит про ведро аккаунта,
+ * идемпотентность и второй платный рендер. Этот приходит тому, кто предъявил
+ * НЕработающий ключ: ни аккаунта, ни рана у него нет, и совет про
+ * `Idempotency-Key` был бы разговором о невозможном.
+ */
+export function authThrottledBody(args) {
+    return rateLimitedError.parse({
+        error: {
+            code: "rate_limited",
+            message: `Too many failed authentication attempts: ${args.limit} per ${args.windowSeconds} seconds ` +
+                `from this address. Retry in ${args.retryAfterSeconds} seconds. ` +
+                `Nothing was charged, and no account was identified.`,
+            limit: args.limit,
+            window_seconds: args.windowSeconds,
+            retry_after_seconds: args.retryAfterSeconds,
+        },
+    });
+}
+//# sourceMappingURL=rate-limit.js.map

package/dist/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"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"}

package/dist/render-backend.d.ts

@@ -1,4 +1,5 @@
 import type { AspectRatio, Resolution } from "./skills.js";
+import type { VendorRefusalClass } from "./vendor-response.js";
 /**
  * Вендор-нейтральный контракт рендера аватара.
  *
@@ -44,8 +45,9 @@ export type ImageSource = {
  */
 export interface AvatarClipRequest {
     /**
-     * Наш run_id. Адаптер обязан пробросить его в идемпотентность вендора
-     * (`Idempotency-Key`, детерминированный от `runId` + шага), если она есть.
+     * Наш run_id. Адаптер обязан пробросить в идемпотентность вендора
+     * (`Idempotency-Key`, если она есть) ОБЛАСТЬ — `idempotencyScope ?? runId`,
+     * а не сам `runId` безусловно: разбор — у поля `idempotencyScope` ниже.
      */
     runId: string;
     /**
@@ -122,10 +124,23 @@ export interface RenderBackend {
      * Реализация обязана:
      *  - разрешать внешность персонажа ВНУТРИ (вендорский каталог), не принимая её
      *    из запроса — идентификаторы аватара и каталог наружу не торчат;
-     *  - слать вендорский `Idempotency-Key`, детерминированный от `req.runId`, —
-     *    вторая независимая линия против двойного списания (подтверждено, docs/13);
-     *  - бросать НЕрайтраебл-ошибку на 4xx кроме 429 — ретрай их не починит;
-     *  - бросать райтраебл-ошибку на 5xx/429 — их ретрай починит.
+     *  - слать вендорский `Idempotency-Key`, детерминированный от ОБЛАСТИ
+     *    идемпотентности (`req.idempotencyScope ?? req.runId`, US-526), — вторая
+     *    независимая линия против двойного списания (подтверждено, docs/13).
+     *    Именно от области, а не от `runId`: у сегментного ролика на один ран
+     *    приходится несколько платных create, и общий ключ заставил бы вендора
+     *    вернуть первый ролик в ответ на каждый следующий — молча и с кодом 200;
+     *  - помечать ошибку признаком `retryable`: 4xx кроме 429 — `false`, 5xx и
+     *    429 — `true`.
+     *
+     * ПРИЗНАК ОПИСЫВАЕТ ПРИРОДУ ОШИБКИ, А НЕ РАЗРЕШЕНИЕ ПОВТОРИТЬ ЭТОТ ВЫЗОВ
+     * (уточнение US-606b, круг 11 внешнего ревью; прежняя редакция говорила «их
+     * ретрай починит» и читалась как позволение). «Транзиентная» и «можно
+     * повторить» — разные утверждения, и для ПЛАТНОГО создания второе всегда
+     * ложно: 429 означает, что вендор отбил, а 5xx — что неизвестно, начал ли он
+     * работу, и повтор превратил бы одно возможное списание в два достоверных.
+     * Признак читается ТОЛЬКО на бесплатном поллинге (`utils/poll-retry.ts`);
+     * `createAvatarJob` не повторяется ни при каком статусе.
      */
     createAvatarJob(req: AvatarClipRequest): Promise<AvatarJobHandle>;
     /**
@@ -141,7 +156,30 @@ export interface RenderBackend {
      * ожидания и бросать по его превышению, а не висеть на зависшей очереди.
      */
     pollAvatarJob(handle: AvatarJobHandle): Promise<AvatarClipResult>;
+    /** Чья причина за отказом: наш счёт у вендора или его беда. ОБЯЗАТЕЛЕН — */
+    /** новый вендор без него не скомпилируется. Разбор — `docs/18` §11.6. */
+    classifyRefusal(error: unknown): VendorRefusalClass;
 }
+/**
+ * ЧИТАТЕЛЬ ПРИЗНАКА, КОТОРЫЙ ТРЕБУЕТ КОНТРАКТ ВЫШЕ (US-606b).
+ *
+ * ЧТО ОН ЧИТАЕТ: природу ошибки, а не разрешение повторить операцию. Кто и что
+ * повторяет — решает вызывающий, и на ПЛАТНОМ создании ответ всегда «ничего»
+ * (см. `createAvatarJob` выше). Сегодня единственный потребитель — ретрай
+ * бесплатного поллинга.
+ *
+ * ЗАЧЕМ ЗДЕСЬ, А НЕ У ВЫЗЫВАЮЩЕГО. Обязанность помечать ошибку записана строкой
+ * выше, и до этой стори её никто не читал: адаптер считал признак, а
+ * потребителя у него не было — то есть контракт держался тестами адаптера на
+ * самого себя. Читатель обязан жить там же, где написана обязанность, иначе он
+ * станет разбором формы КОНКРЕТНОГО адаптера по месту, и второй бэкенд (Argil в
+ * docs/05) выполнит контракт, а вызывающий его не заметит.
+ *
+ * СТРОГОЕ РАВЕНСТВО `true`, А НЕ ПРИВЕДЕНИЕ К ИСТИНЕ: решение о повторе рядом с
+ * деньгами — последнее место, где уместна догадка «похоже на да». Чего в
+ * признаке нет (ошибка без поля, чужой объект, строка) — то не повторяется.
+ */
+export declare function isRetryableVendorError(error: unknown): boolean;
 /**
  * Приведение запроса к возможностям бэкенда.
  *

package/dist/render-backend.js

@@ -1,3 +1,27 @@
+/**
+ * ЧИТАТЕЛЬ ПРИЗНАКА, КОТОРЫЙ ТРЕБУЕТ КОНТРАКТ ВЫШЕ (US-606b).
+ *
+ * ЧТО ОН ЧИТАЕТ: природу ошибки, а не разрешение повторить операцию. Кто и что
+ * повторяет — решает вызывающий, и на ПЛАТНОМ создании ответ всегда «ничего»
+ * (см. `createAvatarJob` выше). Сегодня единственный потребитель — ретрай
+ * бесплатного поллинга.
+ *
+ * ЗАЧЕМ ЗДЕСЬ, А НЕ У ВЫЗЫВАЮЩЕГО. Обязанность помечать ошибку записана строкой
+ * выше, и до этой стори её никто не читал: адаптер считал признак, а
+ * потребителя у него не было — то есть контракт держался тестами адаптера на
+ * самого себя. Читатель обязан жить там же, где написана обязанность, иначе он
+ * станет разбором формы КОНКРЕТНОГО адаптера по месту, и второй бэкенд (Argil в
+ * docs/05) выполнит контракт, а вызывающий его не заметит.
+ *
+ * СТРОГОЕ РАВЕНСТВО `true`, А НЕ ПРИВЕДЕНИЕ К ИСТИНЕ: решение о повторе рядом с
+ * деньгами — последнее место, где уместна догадка «похоже на да». Чего в
+ * признаке нет (ошибка без поля, чужой объект, строка) — то не повторяется.
+ */
+export function isRetryableVendorError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.retryable === true);
+}
 /**
  * Приведение запроса к возможностям бэкенда.
  *

package/dist/render-backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"render-backend.js","sourceRoot":"","sources":["../src/render-backend.ts"],"names":[],"mappings":"AAmJA;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA0D,EAC1D,IAAyB,EACzB,WAAmB;IAEnB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,WAAW,WAAW,oCAAoC,CAAC,CAAC;QAC9E,CAAC;QACD,QAAQ,CAAC,IAAI,CACX,cAAc,UAAU,wBAAwB,WAAW,iBAAiB,QAAQ,EAAE,CACvF,CAAC;QACF,UAAU,GAAG,QAAQ,CAAC;IACxB,CAAC;IAED,IAAI,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;IAClC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,WAAW,WAAW,sCAAsC,CAAC,CAAC;QAChF,CAAC;QACD,QAAQ,CAAC,IAAI,CACX,gBAAgB,WAAW,wBAAwB,WAAW,iBAAiB,QAAQ,EAAE,CAC1F,CAAC;QACF,WAAW,GAAG,QAAQ,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"render-backend.js","sourceRoot":"","sources":["../src/render-backend.ts"],"names":[],"mappings":"AAsKA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAAiC,CAAC,SAAS,KAAK,IAAI,CACtD,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAA0D,EAC1D,IAAyB,EACzB,WAAmB;IAEnB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,IAAI,UAAU,GAAG,GAAG,CAAC,UAAU,CAAC;IAChC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,WAAW,WAAW,oCAAoC,CAAC,CAAC;QAC9E,CAAC;QACD,QAAQ,CAAC,IAAI,CACX,cAAc,UAAU,wBAAwB,WAAW,iBAAiB,QAAQ,EAAE,CACvF,CAAC;QACF,UAAU,GAAG,QAAQ,CAAC;IACxB,CAAC;IAED,IAAI,WAAW,GAAG,GAAG,CAAC,WAAW,CAAC;IAClC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,WAAW,WAAW,sCAAsC,CAAC,CAAC;QAChF,CAAC;QACD,QAAQ,CAAC,IAAI,CACX,gBAAgB,WAAW,wBAAwB,WAAW,iBAAiB,QAAQ,EAAE,CAC1F,CAAC;QACF,WAAW,GAAG,QAAQ,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AAC/C,CAAC"}

package/dist/run-static-warnings.d.ts

@@ -0,0 +1,5 @@
+/** Сохранённый вход нечитаем: перечислить несоблюдённые поля нечем. */
+export declare const UNREADABLE_RUN_INPUT_WARNING = "run input could not be read: parameters that are accepted but not honored cannot be listed for this run";
+export declare function derivedRunWarnings(storedInput: unknown): string[];
+/** Полный `warnings[]` рана. Выводимое первым — тем же порядком, что у `quote`. */
+export declare function composeRunWarnings(stored: unknown, storedInput: unknown): string[];

package/dist/run-static-warnings.js

@@ -0,0 +1,30 @@
+import { makeUgcInput, resolvedScript } from "./skills.js";
+import { dispositionWarnings } from "./contract-dispositions.js";
+import { buildVoiceWarnings } from "./voices.js";
+// Писатели хранят невыводимое, читатель выводит статику. Рационал — docs/18, Д41.
+/** Сохранённый вход нечитаем: перечислить несоблюдённые поля нечем. */
+export const UNREADABLE_RUN_INPUT_WARNING = "run input could not be read: parameters that are accepted but not honored cannot be listed for this run";
+// Реестр диспозиций и языковой warning пресета. Почему без `voice_id` —
+// docs/18, Д41.
+export function derivedRunWarnings(storedInput) {
+    const parsed = makeUgcInput.safeParse(storedInput);
+    if (!parsed.success) {
+        return [UNREADABLE_RUN_INPUT_WARNING];
+    }
+    const input = parsed.data;
+    return [
+        ...dispositionWarnings(input),
+        ...buildVoiceWarnings({ voice: input.voice, script: resolvedScript(input) }),
+    ];
+}
+/** Строки колонки `warnings`; нечитаемое значение даёт пустой список. */
+function storedStrings(stored) {
+    if (!Array.isArray(stored))
+        return [];
+    return stored.filter((item) => typeof item === "string");
+}
+/** Полный `warnings[]` рана. Выводимое первым — тем же порядком, что у `quote`. */
+export function composeRunWarnings(stored, storedInput) {
+    return [...new Set([...derivedRunWarnings(storedInput), ...storedStrings(stored)])];
+}
+//# sourceMappingURL=run-static-warnings.js.map

package/dist/run-static-warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-static-warnings.js","sourceRoot":"","sources":["../src/run-static-warnings.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,kFAAkF;AAElF,uEAAuE;AACvE,MAAM,CAAC,MAAM,4BAA4B,GACvC,yGAAyG,CAAC;AAE5G,wEAAwE;AACxE,gBAAgB;AAChB,MAAM,UAAU,kBAAkB,CAAC,WAAoB;IACrD,MAAM,MAAM,GAAG,YAAY,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,CAAC,4BAA4B,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC;IAC1B,OAAO;QACL,GAAG,mBAAmB,CAAC,KAAK,CAAC;QAC7B,GAAG,kBAAkB,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;KAC7E,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,SAAS,aAAa,CAAC,MAAe;IACpC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC;AAC3E,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,MAAe,EAAE,WAAoB;IACtE,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,kBAAkB,CAAC,WAAW,CAAC,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AACtF,CAAC"}

package/dist/runs.d.ts

@@ -53,6 +53,9 @@ export declare const AI_DISCLOSURE_TEXT = "This video was generated with AI: the
  * всегда и детерминированно, без разбора боксов MP4.
  */
 export declare const AI_DISCLOSURE_OBJECT_METADATA: Readonly<Record<string, string>>;
+/** Форма идентификатора рана. Отдельной схемой, потому что её спрашивают и на */
+/** ВХОДЕ — MCP-тул `get_run`, где голый `z.string()` пускал мусор до сети. */
+export declare const runId: z.ZodString;
 export declare const run: z.ZodObject<{
     run_id: z.ZodString;
     skill: z.ZodString;

package/dist/runs.js

@@ -49,13 +49,30 @@ export const AI_DISCLOSURE_OBJECT_METADATA = {
     generator: "clipwright",
     "ai-disclosure": AI_DISCLOSURE_TEXT,
 };
+/** Форма идентификатора рана. Отдельной схемой, потому что её спрашивают и на */
+/** ВХОДЕ — MCP-тул `get_run`, где голый `z.string()` пускал мусор до сети. */
+export const runId = z.string().regex(/^run_[a-zA-Z0-9]+$/);
 export const run = z.object({
-    run_id: z.string().regex(/^run_[a-zA-Z0-9]+$/),
+    run_id: runId,
     skill: z.string(),
     state: runState,
     credits_reserved: z.number().int().nonnegative(),
     credits_charged: z.number().int().nonnegative().nullable(),
     warnings: z.array(z.string()).default([]),
+    /**
+     * Причина. НЕПУСТОЙ `error` НЕ ЗНАЧИТ `state: "failed"` — и это стало правдой
+     * с clipwright#48, поэтому сказано здесь, в контракте, а не только в коде.
+     *
+     * Второй случай: ран, не доживший до расчёта, чей счёт записал предыдущий
+     * проход сборщика. Его исход НЕИЗВЕСТЕН — успел он отдать видео или упал,
+     * по строке рана не различить, — поэтому состояние остаётся нетерминальным
+     * (врать о нём нельзя), а `error` несёт пометку «нужен разбор человеком».
+     * Пишет её `markRunForReview`.
+     *
+     * ЧТО ИЗ ЭТОГО СЛЕДУЕТ КЛИЕНТУ: опрос по-прежнему ждёт `succeeded` либо
+     * `failed`, а `error` при нетерминальном состоянии читается как объяснение
+     * задержки, а не как исход. Ран в этом состоянии сам не завершится.
+     */
     error: z.string().nullable(),
     final_output: z
         .object({

package/dist/runs.js.map

@@ -1 +1 @@
-{"version":3,"file":"runs.js","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runs.js","sourceRoot":"","sources":["../src/runs.ts"],"names":[],"mappings":"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"}

package/dist/skills.d.ts

@@ -45,7 +45,23 @@ export declare const DEV_RESOLUTION: Resolution;
  */
 export declare function resolveResolution(requested: Resolution | undefined, isDev: boolean): Resolution;
 /**
- * Потолок длины скрипта (docs/12 §11, ~45с озвучки) — временная замена
+ * ⚠️ ЭТО БАЗИС ВЫВОДА ПОТОЛКА СЛОВ, А НЕ ПОТОЛОК СЕКУНД, и имя переименовано
+ * ровно поэтому (находка внешней приёмки, круг 23). Прежнее — `MAX_SCRIPT_SECONDS`
+ * — читалось как «максимум секунд» и дважды подряд стало источником ДЕНЕЖНОГО
+ * дефекта на публичной странице цены: ею зажимали длительность, обещая клиенту
+ * меньше возможного счёта. Схема ограничивает только СЛОВА; сколько из них выйдет
+ * секунд, не ограничено ничем, потому что гейт пейсинга удалён.
+ *
+ * Число осталось прежним, роль названа честно: это множимое, из которого вместе
+ * с быстрым краем пейсинга получается `MAX_SCRIPT_WORDS`.
+ *
+ * ⚠️ ИСХОДНЫЙ ДОВОД НИЖЕ ОПИСЫВАЕТ ПОЛОЖЕНИЕ ДО УДАЛЕНИЯ ГЕЙТА ПЕЙСИНГА и
+ * оставлен как история, а не как действующее объяснение (находка внешней
+ * приёмки, круг 24): он объясняет число через «~45с озвучки» и пейсинг-гейт,
+ * которого с 2026-07-22 не существует. Действующее объяснение — абзац выше:
+ * это множимое, и ограничивает контракт только слова.
+ *
+ * Исходный довод (docs/12 §11) — временная замена
  * мульти-тейка (docs/12 §3: длинные скрипты раньше резались на несколько
  * тейков, эта логика вырезана на время прототипа). Пока мульти-тейк не
  * вернули, скрипт длиннее одного тейка нужно отклонять на входе, а не
@@ -56,8 +72,17 @@ export declare function resolveResolution(requested: Resolution | undefined, isD
  * потолок секунд без нарушения пейсинг-гейта. Числа пейсинга не дублируем,
  * берём готовые константы из pacing.ts.
  */
-export declare const MAX_SCRIPT_SECONDS = 45;
+export declare const SCRIPT_SECONDS_BASIS = 45;
 export declare const MAX_SCRIPT_WORDS: number;
+/** Потолок длины ЛЮБОГО адреса из чужого тела: без него поле берёт весь потолок */
+/** тела запроса. Число — верхний предел, который переваривает любой браузер и CDN. */
+export declare const MAX_URL_LENGTH = 2048;
+/** ЧТО ДЕЛАЕТ `make_ugc` — один текст на обе контрактные поверхности: публичный */
+/** REST-каталог и MCP `tools/list`. Разойдясь, они описали бы РАЗНЫЙ скилл. */
+export declare const MAKE_UGC_DESCRIPTION: string;
+/** Как ЗВАТЬ скилл по MCP. Отдельно от описания выше: имена соседних тулов и */
+/** поллинг — свойства протокола, и REST-каталогу они не адресованы. */
+export declare const MAKE_UGC_AGENT_PROTOCOL: string;
 /**
  * Сырой zod-shape входа make_ugc — БЕЗ `.refine()`.
  *