@clipwright/core 0.19.0 → 0.21.0

package/dist/contract-dispositions.d.ts

@@ -1,32 +1,13 @@
 import { z } from "zod";
 import { makeUgcInputShape } from "./skills.js";
-/** РЕЕСТР ДИСПОЗИЦИЙ ПОЛЕЙ ВХОДА `make_ugc`: у каждого поля обязано быть записанное */
-/** решение. Тип — страж ПОЛНОТЫ, истинность доказывает egress-тест. */
-/**
- * Версия публичного контракта. Отдаётся заголовком `X-Clipwright-Contract` и
- * полем `contract_version` в ответе quote. Любое следующее ломающее изменение
- * обязано её двигать; до этого пересмотра версии не было вообще, поэтому первое
- * её значение совпадает с месяцем самого пересмотра.
- */
+/** Disposition registry for `make_ugc` input fields: every field must have a recorded */
+/** decision. The type guards completeness; the egress test proves truth. */
+/** Public contract version, sent as the `X-Clipwright-Contract` header and as `contract_version` */
+/** in the quote response. Every breaking change must bump it. */
 export declare const CONTRACT_VERSION = "2026-09-14";
 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`.
- */
+/** `implemented`: reaches the vendor or the composition tree; `rejected`: 400 before any run or reserve; */
+/** `warned`: accepted with a `warnings[]` entry. `triggersWhen` keeps defaulted fields quiet on the happy path. */
 export type Disposition = {
     kind: "stored";
     message: string;
@@ -41,14 +22,8 @@ export type Disposition = {
     warning: string;
     triggersWhen: "present" | "differs-from-default";
 };
-/**
- * Таблица решений. `as const satisfies Record<…>` даёт СРАЗУ ДВА свойства:
- * `satisfies` — страж полноты (поле входа без строки здесь не компилируется),
- * `as const` — литеральные типы, из которых ниже выводится множество
- * отклонённых полей. Обычная аннотация `: Record<…>` дала бы только первое, и
- * `offeredUgcInputShape` пришлось бы перечислять руками — то есть завести
- * второй источник правды ровно там, где мы чиним последствия первого.
- */
+/** `satisfies` guards completeness; `as const` keeps literal types, from which the rejected */
+/** set is derived below instead of being listed by hand. */
 export declare const FIELD_DISPOSITIONS: {
     readonly script: {
         readonly kind: "implemented";
@@ -145,115 +120,46 @@ export declare const FIELD_DISPOSITIONS: {
     };
 };
 export type ContractField = keyof typeof FIELD_DISPOSITIONS;
-/**
- * Операционные переключатели, меняющие диспозицию поля БЕЗ правки кода.
- *
- * Смысл ровно один: погасить инцидент. Исходящая сетевая поверхность (проба
- * чужого `image`) выключается флагом, и тогда поле обязано ОТКЛОНЯТЬСЯ, а не
- * приниматься и тихо игнорироваться — иначе выключение килсвитча само стало бы
- * молчаливой подменой, то есть тем дефектом, который реестр и лечит. Запросы
- * БЕЗ `image` при этом продолжают рендериться на дефолтном актёре.
- */
+/** Operational switches that change a field's disposition without a code change. A disabled */
+/** switch must reject the field, not accept and ignore it. */
 export interface ContractFlags {
     remoteFetch: boolean;
-    /** Стадия композиции (US-527, `CLIPWRIGHT_COMPOSE`). */
+    /** Composition stage (`CLIPWRIGHT_COMPOSE`). */
     compose: boolean;
-    /** Генерация личных актёров (clipwright#120); отсутствие значит «выключено». */
+    /** Personal actor generation; absent means off. */
     actorGeneration?: boolean;
     longForm?: boolean;
 }
-/** `create_actor` открыт только вместе с фетч-поверхностью: без неё личного актёра не отрендерить. */
+/** `create_actor` is open only with the fetch surface: a personal actor cannot render without it. */
 export declare function isActorGenerationEnabled(env?: Record<string, string | undefined>): boolean;
-/**
- * Значение флагов из окружения. Читается один раз на процесс: килсвитч ставится
- * на деплое, а не меняется от запроса к запросу, и `tools/list` не должен
- * дрожать между двумя соседними вызовами.
- */
+/** Flags from the environment, read once per process: a kill switch is set at deploy, */
+/** and `tools/list` must not flicker between calls. */
 export declare function contractFlagsFromEnv(env?: Record<string, string | undefined>): ContractFlags;
 export declare function isLongFormQualificationEnabled(env?: Record<string, string | undefined>): boolean;
 export declare const LONG_FORM_DISABLED_MESSAGE = "long-form qualification is disabled on this deployment; pass script without segments or inserts";
+/** Dispositions with flags applied: the base table says what the code can do, this */
+/** says what it offers right now. */
 export declare function resolveDispositions(flags: ContractFlags): Record<ContractField, Disposition>;
-/**
- * ДЕЙСТВУЮЩАЯ таблица процесса — то, из чего строятся все поверхности.
- *
- * Отличается от `FIELD_DISPOSITIONS` ровно на применённые флаги: базовая
- * таблица говорит, что код УМЕЕТ, эта — что он предлагает прямо сейчас.
- */
+/** The process's effective table, from which every surface is built: `FIELD_DISPOSITIONS` */
+/** with the flags applied. */
 export declare const EFFECTIVE_DISPOSITIONS: Record<"actor_gender" | "actor_id" | "aspect_ratio" | "background" | "broll_policy" | "broll_url" | "caption_style" | "captions" | "character" | "disclosure_overlay" | "image" | "inserts" | "look" | "name" | "person" | "resolution" | "script" | "segments" | "tts_model" | "voice" | "voice_id" | "webhook_url", Disposition>;
 type RejectedField = {
     [K in ContractField]: (typeof FIELD_DISPOSITIONS)[K]["kind"] extends "rejected" ? K : never;
 }[ContractField];
-/**
- * Множество предлагаемых полей считается по БАЗОВОЙ таблице — и на уровне
- * типов, и на уровне значения (см. примечание о топологии ниже). Килсвитч —
- * аварийное состояние сервера, а не форма контракта.
- */
+/** Offered fields come from the base table, in types and values alike: a kill switch */
+/** is a server emergency state, not the shape of the contract. */
 type OfferedField = Exclude<ContractField, RejectedField>;
-/**
- * Текст диспозиции для JSON-Schema `description` (блокер B9).
- *
- * ЗАЧЕМ: `offeredUgcInputShape` убирает отклонённое поле из схемы, но там, где
- * поле почему-либо остаётся видимым, вызыватель обязан прочитать ПРИЧИНУ прямо
- * в описании. Тогда самоописательность — свойство схемы по построению, а не
- * разовая правка двух файлов, которую следующее поле воспроизведёт заново.
- */
-/**
- * Примечание для JSON-Schema `description` — по БАЗОВОЙ таблице.
- *
- * Варианта «по действующей таблице» здесь нет НАМЕРЕННО, и это следствие
- * топологии: схему видит клиент, а флаги принадлежат серверу. Причину
- * аварийного отказа вызыватель узнаёт из текста 400, а не из описания поля,
- * которое у него в схеме и так осталось.
- */
+/** Disposition note for the JSON Schema `description`, from the base table: the schema */
+/** belongs to the client, the flags to the server, whose 400 text names emergency refusals. */
 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`.
- */
+/** Full input shape where every unhonored field carries its reason. For surfaces that list */
+/** all fields; offer fields to callers from `offeredUgcInputShape` instead. */
 export declare const annotatedUgcInputShape: typeof makeUgcInputShape;
-/**
- * ПРЕДЛАГАЕМАЯ поверхность входа = полный shape МИНУС отклонённые поля
- * (блокер B4).
- *
- * Отбивать отклонённое поле четырёхсотым, продолжая объявлять его в
- * `tools/list`, в `--help` и в типах SDK, — это «предлагаем и наказываем»:
- * агент читает схему, видит `character`, вызывает и получает 400. Множество
- * выводится ИЗ РЕЕСТРА, поэтому смена диспозиции переносит поле между
- * поверхностями одной строкой, а не правкой каждого потребителя.
- */
+/** Offered input surface = full shape minus rejected fields, so no schema offers a field */
+/** that then gets a 400. Derived from the registry, so one line moves a field. */
 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 ждал бы полностью заполненный объект.
- */
+/** Input type for SDK/CLI/MCP, from the offered shape. Separate from `MakeUgcInput` (the */
+/** `z.infer` output, where defaults are required) so callers need not fill every field. */
 export declare const offeredUgcInput: z.ZodObject<{
     script: z.ZodOptional<z.ZodString>;
     segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -348,63 +254,32 @@ export declare const offeredUgcInput: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export type MakeUgcInputArgs = z.input<typeof offeredUgcInput>;
-/** Одно отклонённое поле, найденное во входе: имя и причина отказа. */
+/** One rejected field found in the input: its name and the refusal reason. */
 export interface RejectedFieldHit {
     field: ContractField;
     message: string;
 }
-/**
- * Отклонённые поля, ПРИСУТСТВУЮЩИЕ во входе. Один вызов — три поверхности:
- * зовётся на входе API (400 до создания рана и до резервирования кредитов), в
- * MCP и в SDK.
- */
+/** Rejected fields present in the input. Called by the API (400 before a run or a */
+/** reserve), by MCP and by the SDK. */
 export declare function rejectedFields(input: Readonly<Record<string, unknown>>): RejectedFieldHit[];
-/** Ключ тела вне контракта и поле, на которое он похож, если такое есть. */
+/** A body key outside the contract and the field it resembles, if any. */
 export interface UnknownFieldHit {
     field: string;
     suggestion?: string | undefined;
 }
-/** Поля, которые предлагаются клиенту: отклонённые в перечень не входят. */
+/** Fields offered to the client; rejected ones are not listed. */
 export declare const ACCEPTED_UGC_FIELDS: string[];
-/** Ключи вне перечня `fields` (по умолчанию — контракт). Отклонённые поля контракта */
-/** сюда не попадают — их называет `rejectedFields` своей причиной (clipwright#166). */
+/** Keys outside `fields` (the contract by default). Rejected contract fields are not */
+/** included: `rejectedFields` names them with their reason. */
 export declare function unknownFields(raw: unknown, fields?: readonly string[]): UnknownFieldHit[];
-/**
- * Warnings реестра для входа рана (правило проекта №3).
- *
- * Вход ожидается УЖЕ РАСПАРСЕННЫМ: дефолты подставлены, поэтому сравнение с
- * дефолтом различает «клиент промолчал» и «клиент явно попросил другое».
- * Сравнение через `===` достаточно: все дефолтные значения контракта —
- * примитивы (строка или булев).
- *
- * Это статические тексты диспозиций. ДИНАМИЧЕСКИЕ warnings (подмена
- * разрешения/формата, голосовые) порождаются именованными генераторами
- * (`negotiateCapabilities`, `buildVoiceWarnings`,
- * `RAW_VOICE_ID_VALIDATION_WARNING`) — каждый со своим тестом; реестр их не
- * поглощает и на них не претендует.
- */
+/** Registry warnings for a parsed run input; defaults are filled in, so `===` tells silence */
+/** from an explicit different value. Dynamic warnings come from their own generators. */
 export declare function dispositionWarnings(input: Readonly<Record<string, unknown>>): string[];
-/**
- * Поля с диспозицией `implemented` — вход мета-тестов покрытия.
- *
- * Считается по БАЗОВОЙ таблице, а не по действующей: доказательство относится к
- * КОДУ, и выключенный операционный килсвитч его не отменяет.
- */
+/** Fields with an `implemented` disposition, input to the coverage meta-tests. From the */
+/** base table: proof belongs to the code, and a disabled kill switch does not revoke it. */
 export declare const IMPLEMENTED_FIELDS: ContractField[];
-/**
- * ДВА РОДА ДОКАЗАТЕЛЬСТВА, И ОНИ НЕ ВЗАИМОЗАМЕНЯЕМЫ (US-527).
- *
- * До этой стори `implemented` означало ровно одно: «поле доезжает до вендора»,
- * и мета-тест сверял весь список с egress-покрытием. Композиция ввела второй
- * род: `background` до вендора не доезжает НИКОГДА — он применяется у нас, уже
- * после того как вендор отдал клип. Сверять его egress-тестом бессмысленно,
- * а записать в тот же список — значит либо получить вечно красный мета-тест,
- * либо ослабить его до бесполезности.
- *
- * Поэтому список разделён по `provenBy`, и у каждого рода — свой мета-тест:
- * egress-поля сверяются с захватом исходящих запросов, композиционные — с
- * тестами стадии композиции.
- */
+/** Two kinds of proof, not interchangeable: egress fields are checked against captured */
+/** outgoing requests, composition fields (applied after the vendor) against composition tests. */
 export declare const EGRESS_PROVEN_FIELDS: ContractField[];
 export declare const COMPOSITION_PROVEN_FIELDS: ContractField[];
 export {};