@clipwright/core 0.1.0

package/dist/contract-dispositions.d.ts

@@ -0,0 +1,335 @@
+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 declare const CONTRACT_VERSION = "2026-08";
+export declare const CONTRACT_VERSION_HEADER = "X-Clipwright-Contract";
+/**
+ * Решение по одному полю входа.
+ *
+ * `implemented` — поле доезжает до вендора или до дерева композиции; `provenBy`
+ *   называет, ЧЕМ это доказано, и мета-тест требует наличия такого теста.
+ * `rejected` — поле не работает и приниматься не должно: 400 на входе, до
+ *   создания рана и до резервирования кредитов.
+ * `warned` — поле не работает, но отказ был бы хуже принятия (ломал бы
+ *   happy-path или дефолт), поэтому несоблюдение объявляется в `warnings[]`.
+ *
+ * `triggersWhen` существует потому, что часть полей объявлена с `.default()` и
+ * после `parse` присутствует ВСЕГДА. Предикат «поле присутствует → warning»
+ * выдавал бы предупреждение на каждом дефолтном happy-path — прямое нарушение
+ * записанного в нашем же коде теста допустимости (`voices.ts`, условие (iii)).
+ * Для полей с дефолтом предикат — `differs-from-default`, для чисто
+ * опциональных — `present`.
+ */
+export type Disposition = {
+    kind: "implemented";
+    provenBy: "egress" | "composition";
+} | {
+    kind: "rejected";
+    message: string;
+} | {
+    kind: "warned";
+    warning: string;
+    triggersWhen: "present" | "differs-from-default";
+};
+/**
+ * Таблица решений. `as const satisfies Record<…>` даёт СРАЗУ ДВА свойства:
+ * `satisfies` — страж полноты (поле входа без строки здесь не компилируется),
+ * `as const` — литеральные типы, из которых ниже выводится множество
+ * отклонённых полей. Обычная аннотация `: Record<…>` дала бы только первое, и
+ * `offeredUgcInputShape` пришлось бы перечислять руками — то есть завести
+ * второй источник правды ровно там, где мы чиним последствия первого.
+ */
+export declare const FIELD_DISPOSITIONS: {
+    readonly script: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly voice: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly voice_id: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly person: {
+        readonly kind: "warned";
+        readonly warning: "person is not honored yet: every clip is rendered with the default actor";
+        readonly triggersWhen: "present";
+    };
+    readonly name: {
+        readonly kind: "warned";
+        readonly warning: "name is not honored yet: it does not reach the renderer";
+        readonly triggersWhen: "present";
+    };
+    readonly look: {
+        readonly kind: "warned";
+        readonly warning: "look is not honored yet: it does not reach the renderer";
+        readonly triggersWhen: "differs-from-default";
+    };
+    readonly captions: {
+        readonly kind: "warned";
+        readonly warning: "captions requested but not rendered in this prototype (stage-B)";
+        readonly triggersWhen: "differs-from-default";
+    };
+    readonly caption_style: {
+        readonly kind: "warned";
+        readonly warning: "caption_style is not honored: captions are not rendered in this prototype (stage-B)";
+        readonly triggersWhen: "differs-from-default";
+    };
+    readonly resolution: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly aspect_ratio: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly image: {
+        readonly kind: "implemented";
+        readonly provenBy: "egress";
+    };
+    readonly segments: {
+        readonly kind: "rejected";
+        readonly message: "segmented clips are not available yet: pass `script` with the full spoken text instead";
+    };
+    readonly character: {
+        readonly kind: "rejected";
+        readonly 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";
+    };
+    readonly broll_url: {
+        readonly kind: "rejected";
+        readonly message: "broll_url is not supported yet: b-roll requires segmented composition. Omit it";
+    };
+    readonly disclosure_overlay: {
+        readonly kind: "implemented";
+        readonly provenBy: "composition";
+    };
+    readonly background: {
+        readonly kind: "implemented";
+        readonly provenBy: "composition";
+    };
+    readonly webhook_url: {
+        readonly kind: "rejected";
+        readonly message: "webhook_url is not supported: no webhook is ever delivered. Poll get_run with the run_id instead";
+    };
+};
+export type ContractField = keyof typeof FIELD_DISPOSITIONS;
+/**
+ * Операционные переключатели, меняющие диспозицию поля БЕЗ правки кода.
+ *
+ * Смысл ровно один: погасить инцидент. Исходящая сетевая поверхность (проба
+ * чужого `image`) выключается флагом, и тогда поле обязано ОТКЛОНЯТЬСЯ, а не
+ * приниматься и тихо игнорироваться — иначе выключение килсвитча само стало бы
+ * молчаливой подменой, то есть тем дефектом, который реестр и лечит. Запросы
+ * БЕЗ `image` при этом продолжают рендериться на дефолтном актёре.
+ */
+export interface ContractFlags {
+    remoteFetch: boolean;
+    /** Стадия композиции (US-527, `CLIPWRIGHT_COMPOSE`). */
+    compose: boolean;
+}
+/**
+ * Значение флагов из окружения. Читается один раз на процесс: килсвитч ставится
+ * на деплое, а не меняется от запроса к запросу, и `tools/list` не должен
+ * дрожать между двумя соседними вызовами.
+ */
+export declare function contractFlagsFromEnv(env?: Record<string, string | undefined>): ContractFlags;
+export declare function resolveDispositions(flags: ContractFlags): Record<ContractField, Disposition>;
+/**
+ * ДЕЙСТВУЮЩАЯ таблица процесса — то, из чего строятся все поверхности.
+ *
+ * Отличается от `FIELD_DISPOSITIONS` ровно на применённые флаги: базовая
+ * таблица говорит, что код УМЕЕТ, эта — что он предлагает прямо сейчас.
+ */
+export declare const EFFECTIVE_DISPOSITIONS: Record<"aspect_ratio" | "background" | "broll_url" | "caption_style" | "captions" | "character" | "disclosure_overlay" | "image" | "look" | "name" | "person" | "resolution" | "script" | "segments" | "voice" | "voice_id" | "webhook_url", Disposition>;
+type RejectedField = {
+    [K in ContractField]: (typeof FIELD_DISPOSITIONS)[K]["kind"] extends "rejected" ? K : never;
+}[ContractField];
+/**
+ * Множество предлагаемых полей считается по БАЗОВОЙ таблице — и на уровне
+ * типов, и на уровне значения (см. примечание о топологии ниже). Килсвитч —
+ * аварийное состояние сервера, а не форма контракта.
+ */
+type OfferedField = Exclude<ContractField, RejectedField>;
+/**
+ * Текст диспозиции для JSON-Schema `description` (блокер B9).
+ *
+ * ЗАЧЕМ: `offeredUgcInputShape` убирает отклонённое поле из схемы, но там, где
+ * поле почему-либо остаётся видимым, вызыватель обязан прочитать ПРИЧИНУ прямо
+ * в описании. Тогда самоописательность — свойство схемы по построению, а не
+ * разовая правка двух файлов, которую следующее поле воспроизведёт заново.
+ */
+/**
+ * Примечание для JSON-Schema `description` — по БАЗОВОЙ таблице.
+ *
+ * Варианта «по действующей таблице» здесь нет НАМЕРЕННО, и это следствие
+ * топологии: схему видит клиент, а флаги принадлежат серверу. Причину
+ * аварийного отказа вызыватель узнаёт из текста 400, а не из описания поля,
+ * которое у него в схеме и так осталось.
+ */
+export declare function dispositionNote(field: ContractField): string | null;
+/**
+ * ПРИМЕЧАНИЕ О ТОПОЛОГИИ, БЕЗ КОТОРОГО ВЫБОР НИЖЕ ВЫГЛЯДИТ ПРОИЗВОЛЬНЫМ.
+ *
+ * `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 declare const annotatedUgcInputShape: typeof makeUgcInputShape;
+/**
+ * ПРЕДЛАГАЕМАЯ поверхность входа = полный shape МИНУС отклонённые поля
+ * (блокер B4).
+ *
+ * Отбивать отклонённое поле четырёхсотым, продолжая объявлять его в
+ * `tools/list`, в `--help` и в типах SDK, — это «предлагаем и наказываем»:
+ * агент читает схему, видит `character`, вызывает и получает 400. Множество
+ * выводится ИЗ РЕЕСТРА, поэтому смена диспозиции переносит поле между
+ * поверхностями одной строкой, а не правкой каждого потребителя.
+ */
+export declare const offeredUgcInputShape: Pick<typeof makeUgcInputShape, OfferedField>;
+/**
+ * Тип ВХОДА для SDK/CLI/MCP — выводится из ПРЕДЛАГАЕМОГО shape, а не из
+ * полного (блокер B4 на поверхности типов). Раньше он строился из полной схемы,
+ * и TypeScript-пользователь получал автокомплит на `character`/`webhook_url`,
+ * вызывал и получал 400 — тот же дефект «предлагаем и наказываем», только не в
+ * MCP. По правилу проекта №2 типы SDK — контрактная поверхность наравне с
+ * остальными.
+ *
+ * ЗАЧЕМ отдельно от `MakeUgcInput` (= выход `z.infer`, где дефолты уже
+ * обязательны): без него SDK ждал бы полностью заполненный объект.
+ */
+export declare const offeredUgcInput: z.ZodObject<{
+    script: z.ZodOptional<z.ZodString>;
+    person: z.ZodOptional<z.ZodString>;
+    image: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    captions: z.ZodDefault<z.ZodBoolean>;
+    caption_style: z.ZodDefault<z.ZodEnum<{
+        hormozi: "hormozi";
+        minimal: "minimal";
+        tiktok: "tiktok";
+    }>>;
+    look: z.ZodDefault<z.ZodEnum<{
+        commercial: "commercial";
+        natural: "natural";
+        raw_iphone: "raw_iphone";
+    }>>;
+    aspect_ratio: z.ZodOptional<z.ZodEnum<{
+        "16:9": "16:9";
+        "1:1": "1:1";
+        "9:16": "9:16";
+    }>>;
+    resolution: z.ZodOptional<z.ZodEnum<{
+        "1080p": "1080p";
+        "4k": "4k";
+        "720p": "720p";
+    }>>;
+    voice: z.ZodOptional<z.ZodEnum<{
+        daria_ru_female: "daria_ru_female";
+        eric: "eric";
+        george: "george";
+        owner_ru_clone: "owner_ru_clone";
+        sarah: "sarah";
+    }>>;
+    voice_id: z.ZodOptional<z.ZodString>;
+    disclosure_overlay: z.ZodOptional<z.ZodBoolean>;
+    background: z.ZodOptional<z.ZodEnum<{
+        blur: "blur";
+        contain: "contain";
+        white: "white";
+    }>>;
+}, z.core.$strip>;
+export type MakeUgcInputArgs = z.input<typeof offeredUgcInput>;
+/** Одно отклонённое поле, найденное во входе: имя и причина отказа. */
+export interface RejectedFieldHit {
+    field: ContractField;
+    message: string;
+}
+/**
+ * Отклонённые поля, ПРИСУТСТВУЮЩИЕ во входе. Один вызов — три поверхности:
+ * зовётся на входе API (400 до создания рана и до резервирования кредитов), в
+ * MCP и в SDK.
+ */
+export declare function rejectedFields(input: Readonly<Record<string, unknown>>): RejectedFieldHit[];
+/**
+ * Warnings реестра для входа рана (правило проекта №3).
+ *
+ * Вход ожидается УЖЕ РАСПАРСЕННЫМ: дефолты подставлены, поэтому сравнение с
+ * дефолтом различает «клиент промолчал» и «клиент явно попросил другое».
+ * Сравнение через `===` достаточно: все дефолтные значения контракта —
+ * примитивы (строка или булев).
+ *
+ * Это статические тексты диспозиций. ДИНАМИЧЕСКИЕ warnings (подмена
+ * разрешения/формата, голосовые) порождаются именованными генераторами
+ * (`negotiateCapabilities`, `buildVoiceWarnings`,
+ * `RAW_VOICE_ID_VALIDATION_WARNING`) — каждый со своим тестом; реестр их не
+ * поглощает и на них не претендует.
+ */
+export declare function dispositionWarnings(input: Readonly<Record<string, unknown>>): string[];
+/**
+ * Поля с диспозицией `implemented` — вход мета-тестов покрытия.
+ *
+ * Считается по БАЗОВОЙ таблице, а не по действующей: доказательство относится к
+ * КОДУ, и выключенный операционный килсвитч его не отменяет.
+ */
+export declare const IMPLEMENTED_FIELDS: ContractField[];
+/**
+ * ДВА РОДА ДОКАЗАТЕЛЬСТВА, И ОНИ НЕ ВЗАИМОЗАМЕНЯЕМЫ (US-527).
+ *
+ * До этой стори `implemented` означало ровно одно: «поле доезжает до вендора»,
+ * и мета-тест сверял весь список с egress-покрытием. Композиция ввела второй
+ * род: `background` до вендора не доезжает НИКОГДА — он применяется у нас, уже
+ * после того как вендор отдал клип. Сверять его egress-тестом бессмысленно,
+ * а записать в тот же список — значит либо получить вечно красный мета-тест,
+ * либо ослабить его до бесполезности.
+ *
+ * Поэтому список разделён по `provenBy`, и у каждого рода — свой мета-тест:
+ * egress-поля сверяются с захватом исходящих запросов, композиционные — с
+ * тестами стадии композиции.
+ */
+export declare const EGRESS_PROVEN_FIELDS: ContractField[];
+export declare const COMPOSITION_PROVEN_FIELDS: ContractField[];
+export {};