@clipwright/core 0.1.0

package/dist/contract-dispositions.js

@@ -0,0 +1,358 @@
+import { z } from "zod";
+import { makeUgcInputShape } from "./skills.js";
+/**
+ * РЕЕСТР ДИСПОЗИЦИЙ ПОЛЕЙ ВХОДА `make_ugc`.
+ *
+ * ЗАЧЕМ ОН ЕСТЬ. Аудит 2026-07-21 показал: из четырнадцати полей публичного
+ * контракта на выход влияли четыре, а десять принимались и МОЛЧА игнорировались
+ * — включая все три поля идентичности и `webhook_url` (клиент подписывался на
+ * уведомление и не получал ничего). Это прямое нарушение правила проекта №3.
+ * Точечная починка вернула бы тот же класс дефекта при следующей фиче, поэтому
+ * лечится не список полей, а МЕХАНИЗМ: у каждого поля обязано быть записанное
+ * решение, и отсутствие решения ловится компилятором.
+ *
+ * ЧТО ЭТОТ ФАЙЛ НЕ ДЕЛАЕТ — И ЭТО ГЛАВНОЕ. Тип `Record<keyof …, Disposition>`
+ * — страж ПОЛНОТЫ, а не ИСТИННОСТИ: он ловит отсутствие строки, но не её
+ * неверность. Именно так `resolution` числился бы «работающим», хотя адаптер
+ * шлёт вендору литерал. Истинность строки `implemented` доказывает EGRESS-ТЕСТ
+ * (`contract-dispositions.egress.test.ts`): изменение значения поля обязано
+ * давать наблюдаемое различие в захваченном теле исходящего запроса вендору.
+ * Запись без egress-теста считается недоказанной — за этим следит мета-тест.
+ */
+/**
+ * Версия публичного контракта. Отдаётся заголовком `X-Clipwright-Contract` и
+ * полем `contract_version` в ответе quote. Любое следующее ломающее изменение
+ * обязано её двигать; до этого пересмотра версии не было вообще, поэтому первое
+ * её значение совпадает с месяцем самого пересмотра.
+ */
+export const CONTRACT_VERSION = "2026-08";
+export const CONTRACT_VERSION_HEADER = "X-Clipwright-Contract";
+/**
+ * Таблица решений. `as const satisfies Record<…>` даёт СРАЗУ ДВА свойства:
+ * `satisfies` — страж полноты (поле входа без строки здесь не компилируется),
+ * `as const` — литеральные типы, из которых ниже выводится множество
+ * отклонённых полей. Обычная аннотация `: Record<…>` дала бы только первое, и
+ * `offeredUgcInputShape` пришлось бы перечислять руками — то есть завести
+ * второй источник правды ровно там, где мы чиним последствия первого.
+ */
+export const FIELD_DISPOSITIONS = {
+    script: { kind: "implemented", provenBy: "egress" },
+    voice: { kind: "implemented", provenBy: "egress" },
+    voice_id: { kind: "implemented", provenBy: "egress" },
+    // Поля, которые не доезжают до рендера и объявляются несоблюдёнными.
+    person: {
+        kind: "warned",
+        warning: "person is not honored yet: every clip is rendered with the default actor",
+        triggersWhen: "present",
+    },
+    name: {
+        kind: "warned",
+        warning: "name is not honored yet: it does not reach the renderer",
+        triggersWhen: "present",
+    },
+    look: {
+        kind: "warned",
+        warning: "look is not honored yet: it does not reach the renderer",
+        triggersWhen: "differs-from-default",
+    },
+    captions: {
+        kind: "warned",
+        warning: "captions requested but not rendered in this prototype (stage-B)",
+        triggersWhen: "differs-from-default",
+    },
+    caption_style: {
+        kind: "warned",
+        warning: "caption_style is not honored: captions are not rendered in this prototype (stage-B)",
+        triggersWhen: "differs-from-default",
+    },
+    // US-522 перевёл обе строки из `warned` в `implemented`: адаптер больше не
+    // шлёт вендору литералы `1080p`/`9:16`, а берёт значения из запроса. Именно
+    // `resolution` был самым опасным полем аудита — он ЧИТАЛСЯ в таске и потому
+    // выглядел рабочим, а до вендора не доезжал. Поэтому обе строки прикрыты
+    // egress-тестами: три разрешения обязаны дать три РАЗНЫХ тела `/v3/videos`.
+    resolution: { kind: "implemented", provenBy: "egress" },
+    aspect_ratio: { kind: "implemented", provenBy: "egress" },
+    // US-524 довёл `image` до вендора. Диспозиция ОБУСЛОВЛЕНА килсвитчем
+    // `CLIPWRIGHT_REMOTE_FETCH`: базовая строка здесь — `implemented`, а при
+    // выключенном флаге `resolveDispositions` переводит её в `rejected` (см. ниже).
+    image: { kind: "implemented", provenBy: "egress" },
+    // Отклоняются: принять поле, зная, что оно не работает, план запрещает сам
+    // себе.
+    //
+    // `segments` заведён СХЕМОЙ в Slice 1 и отклоняется до Slice 2. Именно так
+    // страж и должен был сработать: поле добавили — компиляция упала, пока
+    // решение не записано. Новое поле без решения не проезжает, кем бы оно ни
+    // было добавлено, включая сам план.
+    //
+    // ПОЧЕМУ `rejected` ПЕРЕЖИЛ US-526 (решение владельца 2026-07-22). План
+    // переключал строку на `implemented` с `provenBy: "composition"` уже в
+    // US-526, но композиция приезжает только в US-527: без неё N клипов не
+    // сводятся в один файл и `final_output` предъявить нечем. `implemented`
+    // означает здесь «доказано тестом», а доказывать было бы нечем — то есть
+    // строка обещала бы работу, которой нет. US-526 построил механику
+    // (раскладку ключей, посегментную озвучку, вендорские области
+    // идемпотентности); переключение — одна строка в US-527, когда появится
+    // `composed.mp4`, который её докажет.
+    segments: {
+        kind: "rejected",
+        message: "segmented clips are not available yet: pass `script` with the full spoken text instead",
+    },
+    character: {
+        kind: "rejected",
+        message: "character is not supported: saved characters do not exist yet. Describe the actor with `person` instead, or omit it to use the default actor",
+    },
+    broll_url: {
+        kind: "rejected",
+        message: "broll_url is not supported yet: b-roll requires segmented composition. Omit it",
+    },
+    // Заведено US-528 вместе с самой маркировкой; US-539 перевёл строку из
+    // `rejected` в `implemented`. Плашка требует выжигания в кадр, то есть
+    // композиции, — она появилась в US-527 и доказана живым `composed.mp4`.
+    // Диспозиция ОБУСЛОВЛЕНА килсвитчем `CLIPWRIGHT_COMPOSE` тем же приёмом, что
+    // и `background`: при выключенной стадии выжечь плашку некому, и поле снова
+    // отклоняется, а не принимается и тихо игнорируется.
+    disclosure_overlay: { kind: "implemented", provenBy: "composition" },
+    // Заведено US-527 вместе с самой укладкой. Поле принимается только тогда,
+    // когда композиция действительно кладёт клип в кадр — до этого оно обещало
+    // бы выбор фона, которого некому исполнить. Переключение доказывается
+    // рендером, а не готовностью схемы.
+    // US-527 перевёл строку из `rejected` в `implemented`: композиция реально
+    // кладёт клип в кадр и объявляет долю полей в `warnings[]`. Диспозиция
+    // ОБУСЛОВЛЕНА килсвитчем `CLIPWRIGHT_COMPOSE` — как `image` обусловлен
+    // `CLIPWRIGHT_REMOTE_FETCH`: при выключенной стадии поле снова отклоняется,
+    // потому что исполнять выбор фона в этот момент некому.
+    background: { kind: "implemented", provenBy: "composition" },
+    // ЕДИНСТВЕННАЯ форма раскрытия, которая доходит. Проигнорированный `look`
+    // портит кадр — пользователь видит результат. Проигнорированный
+    // `webhook_url` ломает интеграцию: агент подписался и ПЕРЕСТАЛ поллить, а
+    // `warnings[]` доставляются через `get_run` — по тому самому каналу, от
+    // которого клиент отказался. Предупреждение на канале, который никто не
+    // слушает, раскрытием не является; поэтому здесь только синхронный отказ.
+    webhook_url: {
+        kind: "rejected",
+        message: "webhook_url is not supported: no webhook is ever delivered. Poll get_run with the run_id instead",
+    },
+};
+/** Поля входа в порядке объявления shape — детерминированный обход реестра. */
+const CONTRACT_FIELDS = Object.keys(makeUgcInputShape);
+/**
+ * Значение флагов из окружения. Читается один раз на процесс: килсвитч ставится
+ * на деплое, а не меняется от запроса к запросу, и `tools/list` не должен
+ * дрожать между двумя соседними вызовами.
+ */
+export function contractFlagsFromEnv(env = process.env) {
+    return {
+        remoteFetch: env.CLIPWRIGHT_REMOTE_FETCH === "1",
+        compose: env.CLIPWRIGHT_COMPOSE === "1",
+    };
+}
+const REMOTE_FETCH_DISABLED = {
+    kind: "rejected",
+    message: "image is temporarily disabled (remote media fetch is off); omit it to render with the default actor",
+};
+/**
+ * Таблица диспозиций С УЧЁТОМ флагов. Базовая `FIELD_DISPOSITIONS` описывает,
+ * что код умеет; эта функция — что он предлагает ПРЯМО СЕЙЧАС.
+ */
+/** Отказ по `background`, когда стадия композиции выключена. */
+const COMPOSE_DISABLED = {
+    kind: "rejected",
+    message: "background is not available: composition is disabled on this deployment. Request an aspect_ratio close to your image instead",
+};
+/** Отказ по `disclosure_overlay`, когда стадия композиции выключена. */
+const DISCLOSURE_OVERLAY_DISABLED = {
+    kind: "rejected",
+    message: "disclosure_overlay is not available: composition is disabled on this deployment. The output is still marked in the run contract and in the file metadata",
+};
+export function resolveDispositions(flags) {
+    return {
+        ...FIELD_DISPOSITIONS,
+        image: flags.remoteFetch ? FIELD_DISPOSITIONS.image : REMOTE_FETCH_DISABLED,
+        // Тот же приём, что у `image` (US-524): базовая строка объявляет, что поле
+        // РАБОТАЕТ, а выключенный флаг переводит её в отказ. Обещать выбор фона,
+        // когда стадия композиции выключена, значило бы принять поле, которое
+        // некому исполнить.
+        background: flags.compose ? FIELD_DISPOSITIONS.background : COMPOSE_DISABLED,
+        // Та же обусловленность, что у `background`: видимая плашка выжигается
+        // стадией композиции, и при выключенном флаге исполнять её некому.
+        disclosure_overlay: flags.compose
+            ? FIELD_DISPOSITIONS.disclosure_overlay
+            : DISCLOSURE_OVERLAY_DISABLED,
+    };
+}
+/**
+ * ДЕЙСТВУЮЩАЯ таблица процесса — то, из чего строятся все поверхности.
+ *
+ * Отличается от `FIELD_DISPOSITIONS` ровно на применённые флаги: базовая
+ * таблица говорит, что код УМЕЕТ, эта — что он предлагает прямо сейчас.
+ */
+export const EFFECTIVE_DISPOSITIONS = resolveDispositions(contractFlagsFromEnv());
+/**
+ * Дефолт поля — то, что схема подставит на `undefined`. Берём у самой схемы, а
+ * не переписываем значения рядом: второй список дефолтов разошёлся бы с первым
+ * тем же способом, которым разошлись схема и рендер.
+ */
+const FIELD_DEFAULTS = Object.fromEntries(CONTRACT_FIELDS.map((field) => {
+    const parsed = makeUgcInputShape[field].safeParse(undefined);
+    return [field, parsed.success ? parsed.data : undefined];
+}));
+/**
+ * Текст диспозиции для JSON-Schema `description` (блокер B9).
+ *
+ * ЗАЧЕМ: `offeredUgcInputShape` убирает отклонённое поле из схемы, но там, где
+ * поле почему-либо остаётся видимым, вызыватель обязан прочитать ПРИЧИНУ прямо
+ * в описании. Тогда самоописательность — свойство схемы по построению, а не
+ * разовая правка двух файлов, которую следующее поле воспроизведёт заново.
+ */
+/**
+ * Примечание для JSON-Schema `description` — по БАЗОВОЙ таблице.
+ *
+ * Варианта «по действующей таблице» здесь нет НАМЕРЕННО, и это следствие
+ * топологии: схему видит клиент, а флаги принадлежат серверу. Причину
+ * аварийного отказа вызыватель узнаёт из текста 400, а не из описания поля,
+ * которое у него в схеме и так осталось.
+ */
+export function dispositionNote(field) {
+    return noteFor(FIELD_DISPOSITIONS[field]);
+}
+function noteFor(disposition) {
+    if (disposition.kind === "rejected") {
+        return `REJECTED: ${disposition.message}`;
+    }
+    if (disposition.kind === "warned") {
+        return `NOT HONORED YET: ${disposition.warning}`;
+    }
+    return null;
+}
+function annotate(field) {
+    const note = dispositionNote(field);
+    const schema = makeUgcInputShape[field];
+    return (note ? schema.describe(note) : schema);
+}
+/**
+ * ПРИМЕЧАНИЕ О ТОПОЛОГИИ, БЕЗ КОТОРОГО ВЫБОР НИЖЕ ВЫГЛЯДИТ ПРОИЗВОЛЬНЫМ.
+ *
+ * `offeredUgcInputShape` порождает `tools/list` MCP-сервера, а MCP-сервер —
+ * stdio-процесс НА МАШИНЕ ПОЛЬЗОВАТЕЛЯ, говорящий с нашим API по HTTP. Значит
+ * его `process.env` — окружение КЛИЕНТА, а не сервера. Строй мы предлагаемую
+ * поверхность по флагам, аварийный рубильник сервера начал бы управлять
+ * клиентской схемой: у пользователя без `CLIPWRIGHT_REMOTE_FETCH` поле `image`
+ * пропадало бы из `tools/list`, даже когда на сервере оно работает, — и
+ * наоборот, выставив переменную у себя, клиент вернул бы поле в схему, а
+ * сервер ответил бы 400.
+ *
+ * Поэтому граница проведена так:
+ *  - ЧТО ПРЕДЛАГАЕТСЯ (схема, типы SDK, `--help`) — из БАЗОВОЙ таблицы: это
+ *    форма контракта, одинаковая у всех;
+ *  - ЧТО ПРИНИМАЕТСЯ ПРЯМО СЕЙЧАС (`rejectedFields`, `dispositionWarnings`) —
+ *    из ДЕЙСТВУЮЩЕЙ: это решение сервера, и принимает его сервер.
+ * Килсвитч остаётся аварийным отказом на входе API, а не правкой чужой схемы.
+ */
+/**
+ * Полный shape входа, где каждое несоблюдённое поле несёт причину в описании.
+ * Нужен там, где поверхность обязана показать ВСЕ поля (например, таблица
+ * диспозиций в доках); предлагать поля вызывателю следует не отсюда, а из
+ * `offeredUgcInputShape`.
+ */
+export const annotatedUgcInputShape = Object.fromEntries(CONTRACT_FIELDS.map((field) => [field, annotate(field)]));
+/**
+ * ПРЕДЛАГАЕМАЯ поверхность входа = полный shape МИНУС отклонённые поля
+ * (блокер B4).
+ *
+ * Отбивать отклонённое поле четырёхсотым, продолжая объявлять его в
+ * `tools/list`, в `--help` и в типах SDK, — это «предлагаем и наказываем»:
+ * агент читает схему, видит `character`, вызывает и получает 400. Множество
+ * выводится ИЗ РЕЕСТРА, поэтому смена диспозиции переносит поле между
+ * поверхностями одной строкой, а не правкой каждого потребителя.
+ */
+export const offeredUgcInputShape = Object.fromEntries(CONTRACT_FIELDS.filter((field) => FIELD_DISPOSITIONS[field].kind !== "rejected").map((field) => [field, annotate(field)]));
+/**
+ * Тип ВХОДА для SDK/CLI/MCP — выводится из ПРЕДЛАГАЕМОГО shape, а не из
+ * полного (блокер B4 на поверхности типов). Раньше он строился из полной схемы,
+ * и TypeScript-пользователь получал автокомплит на `character`/`webhook_url`,
+ * вызывал и получал 400 — тот же дефект «предлагаем и наказываем», только не в
+ * MCP. По правилу проекта №2 типы SDK — контрактная поверхность наравне с
+ * остальными.
+ *
+ * ЗАЧЕМ отдельно от `MakeUgcInput` (= выход `z.infer`, где дефолты уже
+ * обязательны): без него SDK ждал бы полностью заполненный объект.
+ */
+export const offeredUgcInput = z.object(offeredUgcInputShape);
+/**
+ * Отклонённые поля, ПРИСУТСТВУЮЩИЕ во входе. Один вызов — три поверхности:
+ * зовётся на входе API (400 до создания рана и до резервирования кредитов), в
+ * MCP и в SDK.
+ */
+export function rejectedFields(input) {
+    const hits = [];
+    for (const field of CONTRACT_FIELDS) {
+        const disposition = EFFECTIVE_DISPOSITIONS[field];
+        if (disposition.kind !== "rejected")
+            continue;
+        if (input[field] === undefined)
+            continue;
+        hits.push({ field, message: disposition.message });
+    }
+    return hits;
+}
+/**
+ * Warnings реестра для входа рана (правило проекта №3).
+ *
+ * Вход ожидается УЖЕ РАСПАРСЕННЫМ: дефолты подставлены, поэтому сравнение с
+ * дефолтом различает «клиент промолчал» и «клиент явно попросил другое».
+ * Сравнение через `===` достаточно: все дефолтные значения контракта —
+ * примитивы (строка или булев).
+ *
+ * Это статические тексты диспозиций. ДИНАМИЧЕСКИЕ warnings (подмена
+ * разрешения/формата, голосовые) порождаются именованными генераторами
+ * (`negotiateCapabilities`, `buildVoiceWarnings`,
+ * `RAW_VOICE_ID_VALIDATION_WARNING`) — каждый со своим тестом; реестр их не
+ * поглощает и на них не претендует.
+ */
+export function dispositionWarnings(input) {
+    const warnings = [];
+    for (const field of CONTRACT_FIELDS) {
+        const disposition = EFFECTIVE_DISPOSITIONS[field];
+        if (disposition.kind !== "warned")
+            continue;
+        const value = input[field];
+        if (value === undefined)
+            continue;
+        if (disposition.triggersWhen === "differs-from-default" &&
+            value === FIELD_DEFAULTS[field]) {
+            continue;
+        }
+        warnings.push(disposition.warning);
+    }
+    return warnings;
+}
+/**
+ * Поля с диспозицией `implemented` — вход мета-тестов покрытия.
+ *
+ * Считается по БАЗОВОЙ таблице, а не по действующей: доказательство относится к
+ * КОДУ, и выключенный операционный килсвитч его не отменяет.
+ */
+export const IMPLEMENTED_FIELDS = CONTRACT_FIELDS.filter((field) => FIELD_DISPOSITIONS[field].kind === "implemented");
+/**
+ * ДВА РОДА ДОКАЗАТЕЛЬСТВА, И ОНИ НЕ ВЗАИМОЗАМЕНЯЕМЫ (US-527).
+ *
+ * До этой стори `implemented` означало ровно одно: «поле доезжает до вендора»,
+ * и мета-тест сверял весь список с egress-покрытием. Композиция ввела второй
+ * род: `background` до вендора не доезжает НИКОГДА — он применяется у нас, уже
+ * после того как вендор отдал клип. Сверять его egress-тестом бессмысленно,
+ * а записать в тот же список — значит либо получить вечно красный мета-тест,
+ * либо ослабить его до бесполезности.
+ *
+ * Поэтому список разделён по `provenBy`, и у каждого рода — свой мета-тест:
+ * egress-поля сверяются с захватом исходящих запросов, композиционные — с
+ * тестами стадии композиции.
+ */
+export const EGRESS_PROVEN_FIELDS = CONTRACT_FIELDS.filter((field) => {
+    const disposition = FIELD_DISPOSITIONS[field];
+    return disposition.kind === "implemented" && disposition.provenBy === "egress";
+});
+export const COMPOSITION_PROVEN_FIELDS = CONTRACT_FIELDS.filter((field) => {
+    const disposition = FIELD_DISPOSITIONS[field];
+    return disposition.kind === "implemented" && disposition.provenBy === "composition";
+});
+//# sourceMappingURL=contract-dispositions.js.map

package/dist/contract-dispositions.js.map

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

package/dist/idempotency.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Отпечаток запроса под ключом идемпотентности + ключ идемпотентности per-client.
+ *
+ * ЗАЧЕМ ЭТОТ МОДУЛЬ ЖИВЁТ ПОДПУТЁМ `@clipwright/core/idempotency`, А НЕ В barrel:
+ * он тянет `node:crypto`. Barrel `@clipwright/core` импортируют И `apps/web`
+ * (через `transpilePackages` в `next.config.ts`), и клиентские компоненты Next.
+ * Стоит `node:crypto` протечь в barrel — `next build` падает на клиентском
+ * бандле. Поэтому barrel НЕ реэкспортирует этот файл; те, кому нужен ключ (SDK,
+ * apps/api), импортируют строго подпуть.
+ */
+/**
+ * Canonical JSON: ключи объектов отсортированы, порядок элементов массива
+ * сохранён (в массиве порядок — часть значения, сортировать его нельзя).
+ *
+ * Нужен потому, что JSON.stringify сохраняет порядок вставки ключей, а он
+ * зависит от того, как агент собрал тело запроса. Два побайтово разных, но
+ * семантически одинаковых запроса обязаны дать один хеш, иначе штатный ретрай
+ * прилетит в 409 и агент будет считать это конфликтом.
+ *
+ * `undefined` внутри объектов отбрасывается — как и в JSON.stringify, чтобы
+ * «ключ отсутствует» и «ключ = undefined» не расходились в хеше.
+ */
+export declare function canonicalize(value: unknown): unknown;
+/**
+ * Хешируется вход ПОСЛЕ zod-парсинга, то есть с уже подставленными дефолтами.
+ * Это осознанная нормализация: «captions не передан» и «captions: false» —
+ * один и тот же запрос и обязаны совпасть по хешу. Хешировать сырое тело
+ * нельзя ещё и потому, что тогда лишний пробел в JSON давал бы 409.
+ */
+export declare function requestHash(input: unknown): string;
+/**
+ * Ключ идемпотентности, детерминированный от входа И идентичности клиента.
+ *
+ * ЗАЧЕМ ПАРСИТЬ ВНУТРИ, А НЕ ПРИНИМАТЬ ГОТОВЫЙ ХЕШ: единственный корректный
+ * путь построить ключ — прогнать сырой вход через `makeUgcInput.parse`, чтобы
+ * подставились дефолты, и только потом канонизировать. Прямой `requestHash`
+ * по сырому телу (без parse) даёт РАЗНЫЕ ключи для «captions не передан» и
+ * «captions: false» — это дефект 3.1 (штатный ретрай агента → ложный новый ран).
+ *
+ * ЗАЧЕМ ПРИМЕШИВАТЬ `clientId`: два разных клиента могут прислать побайтово
+ * один вход; без разделения по клиенту второй получил бы ран первого. `clientId`
+ * идёт ПРЕФИКСОМ хеша — разные клиенты на одном входе дают разные ключи
+ * (дефект 3.2), один клиент на одном входе — стабильный ключ (дедуп денег).
+ */
+export declare function idempotencyKeyFor(input: unknown, clientId: string): string;

package/dist/idempotency.js

@@ -0,0 +1,72 @@
+import { createHash } from "node:crypto";
+import { makeUgcInput } from "./skills.js";
+/**
+ * Отпечаток запроса под ключом идемпотентности + ключ идемпотентности per-client.
+ *
+ * ЗАЧЕМ ЭТОТ МОДУЛЬ ЖИВЁТ ПОДПУТЁМ `@clipwright/core/idempotency`, А НЕ В barrel:
+ * он тянет `node:crypto`. Barrel `@clipwright/core` импортируют И `apps/web`
+ * (через `transpilePackages` в `next.config.ts`), и клиентские компоненты Next.
+ * Стоит `node:crypto` протечь в barrel — `next build` падает на клиентском
+ * бандле. Поэтому barrel НЕ реэкспортирует этот файл; те, кому нужен ключ (SDK,
+ * apps/api), импортируют строго подпуть.
+ */
+/**
+ * Canonical JSON: ключи объектов отсортированы, порядок элементов массива
+ * сохранён (в массиве порядок — часть значения, сортировать его нельзя).
+ *
+ * Нужен потому, что JSON.stringify сохраняет порядок вставки ключей, а он
+ * зависит от того, как агент собрал тело запроса. Два побайтово разных, но
+ * семантически одинаковых запроса обязаны дать один хеш, иначе штатный ретрай
+ * прилетит в 409 и агент будет считать это конфликтом.
+ *
+ * `undefined` внутри объектов отбрасывается — как и в JSON.stringify, чтобы
+ * «ключ отсутствует» и «ключ = undefined» не расходились в хеше.
+ */
+export function canonicalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalize);
+    }
+    if (value !== null && typeof value === "object") {
+        const source = value;
+        const result = {};
+        for (const key of Object.keys(source).sort()) {
+            if (source[key] !== undefined) {
+                result[key] = canonicalize(source[key]);
+            }
+        }
+        return result;
+    }
+    return value;
+}
+/**
+ * Хешируется вход ПОСЛЕ zod-парсинга, то есть с уже подставленными дефолтами.
+ * Это осознанная нормализация: «captions не передан» и «captions: false» —
+ * один и тот же запрос и обязаны совпасть по хешу. Хешировать сырое тело
+ * нельзя ещё и потому, что тогда лишний пробел в JSON давал бы 409.
+ */
+export function requestHash(input) {
+    return createHash("sha256")
+        .update(JSON.stringify(canonicalize(input)))
+        .digest("hex");
+}
+/**
+ * Ключ идемпотентности, детерминированный от входа И идентичности клиента.
+ *
+ * ЗАЧЕМ ПАРСИТЬ ВНУТРИ, А НЕ ПРИНИМАТЬ ГОТОВЫЙ ХЕШ: единственный корректный
+ * путь построить ключ — прогнать сырой вход через `makeUgcInput.parse`, чтобы
+ * подставились дефолты, и только потом канонизировать. Прямой `requestHash`
+ * по сырому телу (без parse) даёт РАЗНЫЕ ключи для «captions не передан» и
+ * «captions: false» — это дефект 3.1 (штатный ретрай агента → ложный новый ран).
+ *
+ * ЗАЧЕМ ПРИМЕШИВАТЬ `clientId`: два разных клиента могут прислать побайтово
+ * один вход; без разделения по клиенту второй получил бы ран первого. `clientId`
+ * идёт ПРЕФИКСОМ хеша — разные клиенты на одном входе дают разные ключи
+ * (дефект 3.2), один клиент на одном входе — стабильный ключ (дедуп денег).
+ */
+export function idempotencyKeyFor(input, clientId) {
+    const parsed = makeUgcInput.parse(input);
+    return createHash("sha256")
+        .update(clientId + JSON.stringify(canonicalize(parsed)))
+        .digest("hex");
+}
+//# sourceMappingURL=idempotency.js.map

package/dist/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../src/idempotency.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C;;;;;;;;;GASG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACjC,CAAC;IAED,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,KAAgC,CAAC;QAChD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC7C,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;SAC3C,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc,EAAE,QAAgB;IAChE,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;SACvD,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./skills.js";
+export * from "./contract-dispositions.js";
+export * from "./aspect.js";
+export * from "./voices.js";
+export * from "./runs.js";
+export * from "./pacing.js";
+export * from "./render-backend.js";
+export * from "./tts-backend.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+export * from "./skills.js";
+// Реестр диспозиций импортирует shape из skills.js — направление одностороннее,
+// цикла нет. Отсюда же приходит MakeUgcInputArgs (выводится из предлагаемого
+// shape, а не из полного).
+export * from "./contract-dispositions.js";
+// Резолвер формата: чистые функции, ноль сети. Импортирует ASPECT_RATIOS из
+// skills.js — направление то же одностороннее, что и у реестра.
+export * from "./aspect.js";
+export * from "./voices.js";
+export * from "./runs.js";
+export * from "./pacing.js";
+// Вендор-нейтральные контракты: всё вендорское живёт в адаптерах, не здесь.
+export * from "./render-backend.js";
+export * from "./tts-backend.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,gFAAgF;AAChF,6EAA6E;AAC7E,2BAA2B;AAC3B,cAAc,4BAA4B,CAAC;AAC3C,4EAA4E;AAC5E,gEAAgE;AAChE,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,4EAA4E;AAC5E,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/pacing.d.ts

@@ -0,0 +1,4 @@
+/** Пейсинг речи (docs/09 §5): 2–4 слова в секунду. */
+export declare const WORDS_PER_SECOND_MIN = 2;
+export declare const WORDS_PER_SECOND_MAX = 4;
+export declare function countWords(script: string): number;

package/dist/pacing.js

@@ -0,0 +1,7 @@
+/** Пейсинг речи (docs/09 §5): 2–4 слова в секунду. */
+export const WORDS_PER_SECOND_MIN = 2;
+export const WORDS_PER_SECOND_MAX = 4;
+export function countWords(script) {
+    return script.trim().split(/\s+/).filter(Boolean).length;
+}
+//# sourceMappingURL=pacing.js.map

package/dist/pacing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pacing.js","sourceRoot":"","sources":["../src/pacing.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AACtC,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;AAC3D,CAAC"}