@clipwright/core 0.1.0

package/dist/render-backend.d.ts

@@ -0,0 +1,157 @@
+import type { AspectRatio, Resolution } from "./skills.js";
+/**
+ * Вендор-нейтральный контракт рендера аватара.
+ *
+ * ЗАЧЕМ: HeyGen — не единственный и не обязательно постоянный провайдер.
+ * В docs/05 уже записан Argil как запасной бэкенд (дешевле по минуте), а
+ * legacy-API самого HeyGen выключается 31.10.2026 — вендорская поверхность
+ * меняется быстрее, чем наш продукт. Всё, что знает про `x-api-key`,
+ * `/v3/videos` и словарь `"1080p"`, живёт ИСКЛЮЧИТЕЛЬНО в адаптере.
+ *
+ * ПРАВИЛО: ни один тип в этом файле не должен быть заимствован из вендорского
+ * ответа. Если поле нельзя объяснить в терминах продукта — ему здесь не место.
+ */
+/** Источник аудио. Загруженный ассет — вендорская деталь, наружу не торчит. */
+export type AudioSource = {
+    kind: "url";
+    url: string;
+} | {
+    kind: "bytes";
+    data: Uint8Array;
+    mimeType: string;
+};
+/**
+ * Источник внешности актёра — ПУБЛИЧНЫЙ URL пользователя, и только он.
+ *
+ * Дискриминируемый союз из одного варианта не избыточен: он фиксирует, что
+ * вторым вариантом никогда не станет вендорский идентификатор. Расширяться он
+ * может кадром или байтами, но не «id аватара из каталога».
+ */
+export type ImageSource = {
+    kind: "url";
+    url: string;
+};
+/**
+ * Запрос на рендер одного клипа.
+ *
+ * ПРО ВНЕШНОСТЬ (инвариант переписан в US-524, а не удалён). Раньше внешности
+ * здесь не было вовсе: её целиком разрешал адаптер, и поле `image` публичного
+ * контракта молча игнорировалось. Теперь внешность приходит СЮДА, но ровно в
+ * одной форме — пользовательский публичный URL. Вендорские идентификаторы
+ * (talking_photo, asset_id) наружу по-прежнему не торчат и остаются заперты в
+ * адаптере; `image` не задан — адаптер резолвит дефолтного актёра сам, как и
+ * прежде. То есть ослаблено ровно одно ограничение, и оно названо.
+ */
+export interface AvatarClipRequest {
+    /**
+     * Наш run_id. Адаптер обязан пробросить его в идемпотентность вендора
+     * (`Idempotency-Key`, детерминированный от `runId` + шага), если она есть.
+     */
+    runId: string;
+    /**
+     * Область вендорской идемпотентности. Не задана — берётся `runId`, то есть
+     * поведение односегментного рана буквально прежнее.
+     *
+     * ЗАЧЕМ ОТДЕЛЬНО ОТ `runId` (US-526): у сегментного ролика на один ран
+     * приходится несколько платных create. Общий на всех ключ означал бы, что
+     * вендор дедуплицирует ВТОРОЙ сегмент в первый и вернёт чужой ролик —
+     * молча и с кодом 200. Разделять обязан вызывающий, потому что только он
+     * знает, чем сегменты различаются.
+     */
+    idempotencyScope?: string;
+    audio: AudioSource;
+    resolution: Resolution;
+    aspectRatio: AspectRatio;
+    /** Не задан — адаптер резолвит дефолтного актёра. */
+    image?: ImageSource;
+}
+export interface AvatarClipResult {
+    /**
+     * URL у вендора. Считается ВРЕМЕННЫМ и непригодным для отдачи клиенту:
+     * у HeyGen это подписанная ссылка с истечением. Пайплайн обязан перелить
+     * файл в наше хранилище и вернуть пользователю уже наш URL.
+     */
+    videoUrl: string;
+    durationSec: number;
+    /** Идентификатор задачи у вендора — без него разбор инцидента на их стороне невозможен. */
+    providerJobId: string;
+    provider: string;
+}
+/**
+ * Хэндл созданной у вендора задачи рендера — мост между ПЛАТНЫМ `createAvatarJob`
+ * и бесплатным `pollAvatarJob`.
+ *
+ * СЕРИАЛИЗУЕМ ПО КОНТРАКТУ (инвариант): таск сохраняет его в R2 как
+ * `runs/{runId}/avatar.job.json` и после падения восстанавливает через
+ * `JSON.parse(JSON.stringify(handle))`. Отсюда: только примитивы — никаких
+ * `Date`, `Uint8Array`, функций; если когда-либо понадобится момент времени,
+ * он кладётся ISO-строкой. Round-trip обязан давать эквивалентный объект,
+ * иначе возобновление поллинга по чекпоинту сломается.
+ */
+export interface AvatarJobHandle {
+    /** Идентификатор задачи у вендора (у HeyGen — `video_id`). */
+    providerJobId: string;
+    /** Имя бэкенда, создавшего задачу, — чтобы поллить её тем же адаптером. */
+    provider: string;
+}
+/**
+ * Возможности бэкенда. Существует, потому что вендоры отличаются в мелочах,
+ * которые ломают гейт: HeyGen отклоняет `480p` и ниже (проверено 18.07.2026,
+ * принимает только 720p/1080p/4k), у другого провайдера набор будет иным.
+ *
+ * Несовпадение НЕ должно приводить к молчаливой подмене — правило проекта №3
+ * требует объявлять несоблюдённые параметры в `warnings[]`.
+ */
+export interface BackendCapabilities {
+    resolutions: readonly Resolution[];
+    aspectRatios: readonly AspectRatio[];
+    /** Максимальная длина одного аудио, сек. null — вендор не документирует. */
+    maxAudioSec: number | null;
+}
+export interface RenderBackend {
+    readonly name: string;
+    readonly capabilities: BackendCapabilities;
+    /**
+     * Создать задачу рендера у вендора. РАЗДЕЛЁН с поллингом намеренно: создание —
+     * ПЛАТНОЕ и однократное, поллинг — бесплатный и возобновляемый. Возврат —
+     * сериализуемый `AvatarJobHandle`, который таск пишет в R2 (`avatar.job.json`)
+     * ДО начала поллинга: падение между «вендор списал деньги» и «ролик перелит в
+     * наше хранилище» возобновляется поллингом сохранённого handle, а не вторым
+     * платным вызовом (ADR-006).
+     *
+     * Реализация обязана:
+     *  - разрешать внешность персонажа ВНУТРИ (вендорский каталог), не принимая её
+     *    из запроса — идентификаторы аватара и каталог наружу не торчат;
+     *  - слать вендорский `Idempotency-Key`, детерминированный от `req.runId`, —
+     *    вторая независимая линия против двойного списания (подтверждено, docs/13);
+     *  - бросать НЕрайтраебл-ошибку на 4xx кроме 429 — ретрай их не починит;
+     *  - бросать райтраебл-ошибку на 5xx/429 — их ретрай починит.
+     */
+    createAvatarJob(req: AvatarClipRequest): Promise<AvatarJobHandle>;
+    /**
+     * Дождаться терминального состояния задачи и вернуть результат. БЕСПЛАТНЫЙ и
+     * идемпотентный: безопасен для повтора и для возобновления по сохранённому
+     * handle.
+     *
+     * Дискриминация терминальности — SUCCESS-WHITELIST (fail-closed): успех — это
+     * ТОЛЬКО явно успешный статус вендора ВМЕСТЕ с непустым URL видео. Любой иной
+     * терминальный ИЛИ неизвестный статус, равно как «успех» без URL, обязан
+     * бросать: молчаливый провал внутри HTTP 200 (у HeyGen — `status: "failed"`)
+     * обычным error-handling не ловится. Реализация обязана иметь верхний предел
+     * ожидания и бросать по его превышению, а не висеть на зависшей очереди.
+     */
+    pollAvatarJob(handle: AvatarJobHandle): Promise<AvatarClipResult>;
+}
+/**
+ * Приведение запроса к возможностям бэкенда.
+ *
+ * Возвращает то, что бэкенд реально может, и список предупреждений о каждом
+ * расхождении. Молча понижать разрешение нельзя: пользователь, заказавший
+ * 1080p и получивший 720p без предупреждения, — это ровно тот дефект
+ * конкурента, который зафиксирован в docs/08 как антипаттерн.
+ */
+export declare function negotiateCapabilities(req: Pick<AvatarClipRequest, "resolution" | "aspectRatio">, caps: BackendCapabilities, backendName: string): {
+    resolution: Resolution;
+    aspectRatio: AspectRatio;
+    warnings: string[];
+};

package/dist/render-backend.js

@@ -0,0 +1,31 @@
+/**
+ * Приведение запроса к возможностям бэкенда.
+ *
+ * Возвращает то, что бэкенд реально может, и список предупреждений о каждом
+ * расхождении. Молча понижать разрешение нельзя: пользователь, заказавший
+ * 1080p и получивший 720p без предупреждения, — это ровно тот дефект
+ * конкурента, который зафиксирован в docs/08 как антипаттерн.
+ */
+export function negotiateCapabilities(req, caps, backendName) {
+    const warnings = [];
+    let resolution = req.resolution;
+    if (!caps.resolutions.includes(resolution)) {
+        const fallback = caps.resolutions.at(-1);
+        if (!fallback) {
+            throw new Error(`backend ${backendName} declares no supported resolutions`);
+        }
+        warnings.push(`resolution ${resolution} is not supported by ${backendName}; rendered at ${fallback}`);
+        resolution = fallback;
+    }
+    let aspectRatio = req.aspectRatio;
+    if (!caps.aspectRatios.includes(aspectRatio)) {
+        const fallback = caps.aspectRatios[0];
+        if (!fallback) {
+            throw new Error(`backend ${backendName} declares no supported aspect ratios`);
+        }
+        warnings.push(`aspect_ratio ${aspectRatio} is not supported by ${backendName}; rendered at ${fallback}`);
+        aspectRatio = fallback;
+    }
+    return { resolution, aspectRatio, warnings };
+}
+//# sourceMappingURL=render-backend.js.map

package/dist/render-backend.js.map

@@ -0,0 +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"}

package/dist/runs.d.ts

@@ -0,0 +1,176 @@
+import { z } from "zod";
+/** Стадии рендер-пайплайна make_ugc (docs/02 §2). */
+export declare const RUN_STATES: readonly ["queued", "scripting", "tts", "avatar", "compositing", "uploading", "succeeded", "failed"];
+export declare const runState: z.ZodEnum<{
+    avatar: "avatar";
+    compositing: "compositing";
+    failed: "failed";
+    queued: "queued";
+    scripting: "scripting";
+    succeeded: "succeeded";
+    tts: "tts";
+    uploading: "uploading";
+}>;
+export type RunState = z.infer<typeof runState>;
+export declare const runStep: z.ZodObject<{
+    step: z.ZodString;
+    state: z.ZodEnum<{
+        failed: "failed";
+        pending: "pending";
+        running: "running";
+        succeeded: "succeeded";
+    }>;
+    started_at: z.ZodNullable<z.ZodString>;
+    finished_at: z.ZodNullable<z.ZodString>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        kind: z.ZodString;
+        url: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Единый объект рана для ЛЮБОГО скилла и маршрута — один неймспейс
+ * /v1/runs/{id}, без протечки внутреннего роутинга (урок из teardown
+ * AgentMedia: реюз-раны у них 404-ят на документированном эндпоинте).
+ */
+/**
+ * МАРКИРОВКА AI-ВЫВОДА — константа, а не строка на каждой поверхности.
+ *
+ * Ст. 50 EU AI Act применяется с 2026-08-02. Юридическую применимость к
+ * прототипу мы не проверяли и не выдаём техническую меру за соответствие; но
+ * ролик, синтезированный целиком, обязан говорить об этом сам — независимо от
+ * того, кто его потом перешлёт.
+ *
+ * Текст живёт ОДНОЙ константой: три поверхности (SDK, CLI, MCP) отдают его
+ * дословно, и разъехавшиеся формулировки означали бы, что раскрытие зависит от
+ * того, каким клиентом пользователь скачал файл.
+ */
+export declare const AI_DISCLOSURE_TEXT = "This video was generated with AI: the actor, the voice and the lip sync are synthetic.";
+/**
+ * Метаданные объекта хранилища (вариант D2) — одна константа, потому что
+ * ключи должны совпадать у писателя и у любого будущего читателя. Носитель
+ * слабее встроенного тега (теряется при пересохранении), зато проставляется
+ * всегда и детерминированно, без разбора боксов MP4.
+ */
+export declare const AI_DISCLOSURE_OBJECT_METADATA: Readonly<Record<string, string>>;
+export declare const run: z.ZodObject<{
+    run_id: z.ZodString;
+    skill: z.ZodString;
+    state: z.ZodEnum<{
+        avatar: "avatar";
+        compositing: "compositing";
+        failed: "failed";
+        queued: "queued";
+        scripting: "scripting";
+        succeeded: "succeeded";
+        tts: "tts";
+        uploading: "uploading";
+    }>;
+    credits_reserved: z.ZodNumber;
+    credits_charged: z.ZodNullable<z.ZodNumber>;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    error: z.ZodNullable<z.ZodString>;
+    final_output: z.ZodNullable<z.ZodObject<{
+        video_url: z.ZodString;
+        video_url_unsubtitled: z.ZodOptional<z.ZodString>;
+        portrait_url: z.ZodOptional<z.ZodString>;
+        character_sheet_url: z.ZodOptional<z.ZodString>;
+        character_id: z.ZodOptional<z.ZodString>;
+        duration_seconds: z.ZodNumber;
+        ai_generated: z.ZodLiteral<true>;
+        ai_disclosure: z.ZodString;
+        requested_aspect_ratio: z.ZodOptional<z.ZodString>;
+        vendor_aspect_ratio: z.ZodOptional<z.ZodString>;
+        final_aspect_ratio: z.ZodOptional<z.ZodString>;
+        composition_policy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        step: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            pending: "pending";
+            running: "running";
+            succeeded: "succeeded";
+        }>;
+        started_at: z.ZodNullable<z.ZodString>;
+        finished_at: z.ZodNullable<z.ZodString>;
+        artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            url: z.ZodString;
+            bytes: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    created_at: z.ZodString;
+    finished_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type Run = z.infer<typeof run>;
+/**
+ * Терминальные состояния рана — РАЗДЕЛЯЕМАЯ константа, единственный источник
+ * истины о завершённости. ЗАЧЕМ отдельно, а не строковые литералы: до US-501
+ * терминальность проверялась `"succeeded"`/`"failed"` в трёх местах (SDK-цикл
+ * `makeUgc`, две ветки MCP `get_run`); расхождение при правке ловилось бы только
+ * в проде.
+ */
+export declare const SUCCEEDED_STATE: "succeeded";
+export declare const FAILED_STATE: "failed";
+export declare const TERMINAL_STATES: readonly ["succeeded", "failed"];
+/**
+ * Толерантная READ-проекция рана: ослабляется РОВНО одно поле — `state`
+ * (enum `runState` → `z.string()`). Все остальные поля, включая
+ * `final_output.portrait_url`/`character_*`, НАСЛЕДУЮТСЯ через `run.extend` —
+ * рукописный форк схемы ЗАПРЕЩЁН (связывающее условие Architect A11): форк молча
+ * ронял бы новые поля `run` из read-контракта, что и есть тот класс дефектов.
+ *
+ * ЗАЧЕМ read/write-асимметрия (docs/12:198): добавление стадии на сервере
+ * (напр. `"publishing"`) сломало бы строгий `run.parse` в `getRun` у КАЖДОГО уже
+ * установленного MCP — неизвестная стадия отверглась бы. Чтение толерантно к
+ * расширению enum стадий; строгость ЗАПИСИ (`run.parse` в `startUgc`) при этом
+ * сохраняется — сервер не должен принимать мусорное тело.
+ */
+export declare const runRead: z.ZodObject<{
+    run_id: z.ZodString;
+    skill: z.ZodString;
+    credits_reserved: z.ZodNumber;
+    credits_charged: z.ZodNullable<z.ZodNumber>;
+    warnings: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    error: z.ZodNullable<z.ZodString>;
+    final_output: z.ZodNullable<z.ZodObject<{
+        video_url: z.ZodString;
+        video_url_unsubtitled: z.ZodOptional<z.ZodString>;
+        portrait_url: z.ZodOptional<z.ZodString>;
+        character_sheet_url: z.ZodOptional<z.ZodString>;
+        character_id: z.ZodOptional<z.ZodString>;
+        duration_seconds: z.ZodNumber;
+        ai_generated: z.ZodLiteral<true>;
+        ai_disclosure: z.ZodString;
+        requested_aspect_ratio: z.ZodOptional<z.ZodString>;
+        vendor_aspect_ratio: z.ZodOptional<z.ZodString>;
+        final_aspect_ratio: z.ZodOptional<z.ZodString>;
+        composition_policy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        step: z.ZodString;
+        state: z.ZodEnum<{
+            failed: "failed";
+            pending: "pending";
+            running: "running";
+            succeeded: "succeeded";
+        }>;
+        started_at: z.ZodNullable<z.ZodString>;
+        finished_at: z.ZodNullable<z.ZodString>;
+        artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            kind: z.ZodString;
+            url: z.ZodString;
+            bytes: z.ZodNumber;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    created_at: z.ZodString;
+    finished_at: z.ZodNullable<z.ZodString>;
+    state: z.ZodString;
+}, z.core.$strip>;
+export type RunRead = z.infer<typeof runRead>;
+/**
+ * Терминален ли ран. Принимает `string` (read-проекция), а не `RunState`,
+ * поэтому неизвестный статус (расширение enum) корректно даёт `false`.
+ */
+export declare function isTerminal(state: string): boolean;

package/dist/runs.js

@@ -0,0 +1,137 @@
+import { z } from "zod";
+/** Стадии рендер-пайплайна make_ugc (docs/02 §2). */
+export const RUN_STATES = [
+    "queued",
+    "scripting",
+    "tts",
+    "avatar",
+    "compositing",
+    "uploading",
+    "succeeded",
+    "failed",
+];
+export const runState = z.enum(RUN_STATES);
+export const runStep = z.object({
+    step: z.string(),
+    state: z.enum(["pending", "running", "succeeded", "failed"]),
+    started_at: z.string().datetime().nullable(),
+    finished_at: z.string().datetime().nullable(),
+    artifacts: z
+        .array(z.object({ kind: z.string(), url: z.string().url(), bytes: z.number().int() }))
+        .default([]),
+});
+/**
+ * Единый объект рана для ЛЮБОГО скилла и маршрута — один неймспейс
+ * /v1/runs/{id}, без протечки внутреннего роутинга (урок из teardown
+ * AgentMedia: реюз-раны у них 404-ят на документированном эндпоинте).
+ */
+/**
+ * МАРКИРОВКА AI-ВЫВОДА — константа, а не строка на каждой поверхности.
+ *
+ * Ст. 50 EU AI Act применяется с 2026-08-02. Юридическую применимость к
+ * прототипу мы не проверяли и не выдаём техническую меру за соответствие; но
+ * ролик, синтезированный целиком, обязан говорить об этом сам — независимо от
+ * того, кто его потом перешлёт.
+ *
+ * Текст живёт ОДНОЙ константой: три поверхности (SDK, CLI, MCP) отдают его
+ * дословно, и разъехавшиеся формулировки означали бы, что раскрытие зависит от
+ * того, каким клиентом пользователь скачал файл.
+ */
+export const AI_DISCLOSURE_TEXT = "This video was generated with AI: the actor, the voice and the lip sync are synthetic.";
+/**
+ * Метаданные объекта хранилища (вариант D2) — одна константа, потому что
+ * ключи должны совпадать у писателя и у любого будущего читателя. Носитель
+ * слабее встроенного тега (теряется при пересохранении), зато проставляется
+ * всегда и детерминированно, без разбора боксов MP4.
+ */
+export const AI_DISCLOSURE_OBJECT_METADATA = {
+    "ai-generated": "true",
+    generator: "clipwright",
+    "ai-disclosure": AI_DISCLOSURE_TEXT,
+};
+export const run = z.object({
+    run_id: z.string().regex(/^run_[a-zA-Z0-9]+$/),
+    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: z.string().nullable(),
+    final_output: z
+        .object({
+        video_url: z.string().url(),
+        video_url_unsubtitled: z.string().url().optional(),
+        portrait_url: z.string().url().optional(),
+        character_sheet_url: z.string().url().optional(),
+        character_id: z.string().optional(),
+        duration_seconds: z.number().positive(),
+        /**
+         * ОБЯЗАТЕЛЬНЫЕ поля маркировки, а не опциональные.
+         *
+         * `z.literal(true)` — не педантизм: опциональное поле можно забыть
+         * проставить, и ролик уедет непомеченным, а схема промолчит. Здесь она
+         * не промолчит — `run.parse` уронит терминальный ответ, и дефект
+         * обнаружится у нас, а не у получателя ролика.
+         */
+        ai_generated: z.literal(true),
+        ai_disclosure: z.string().min(1),
+        /**
+         * ТРИ РАЗНЫХ ФОРМАТА, А НЕ ОДИН (US-527).
+         *
+         * До этой стори ответ нёс одно значение, и по нему нельзя было отличить
+         * «клиент попросил 1:1 и получил 1:1» от «клиент попросил 1:1, вендору
+         * ушло 9:16, а квадрат собрали мы». Живое измерение US-530 показало, что
+         * разница видимая: вендор в одну сторону режет кадр, в другую добивает
+         * белым. Отладка расхождения по одному полю невозможна — оно не хранит
+         * того, что произошло.
+         *
+         * Поля опциональны, потому что заполняются только на пути композиции:
+         * ран без неё отдаёт вендорский файл как есть, и трёх значений у него
+         * нет — есть одно.
+         */
+        requested_aspect_ratio: z.string().optional(),
+        vendor_aspect_ratio: z.string().optional(),
+        final_aspect_ratio: z.string().optional(),
+        /** Как клип уложен в кадр: `exact`, либо режим фона. */
+        composition_policy: z.string().optional(),
+    })
+        .nullable(),
+    steps: z.array(runStep).default([]),
+    created_at: z.string().datetime(),
+    finished_at: z.string().datetime().nullable(),
+});
+/**
+ * Терминальные состояния рана — РАЗДЕЛЯЕМАЯ константа, единственный источник
+ * истины о завершённости. ЗАЧЕМ отдельно, а не строковые литералы: до US-501
+ * терминальность проверялась `"succeeded"`/`"failed"` в трёх местах (SDK-цикл
+ * `makeUgc`, две ветки MCP `get_run`); расхождение при правке ловилось бы только
+ * в проде.
+ */
+export const SUCCEEDED_STATE = "succeeded";
+export const FAILED_STATE = "failed";
+// Различение исхода у потребителей — ТОЛЬКО через именованные константы выше:
+// позиционный `TERMINAL_STATES[1]` при переупорядочивании массива молча
+// инвертировал бы успех/провал (вердикт Architect, Фаза 2 Этапа 5).
+export const TERMINAL_STATES = [SUCCEEDED_STATE, FAILED_STATE];
+/**
+ * Толерантная READ-проекция рана: ослабляется РОВНО одно поле — `state`
+ * (enum `runState` → `z.string()`). Все остальные поля, включая
+ * `final_output.portrait_url`/`character_*`, НАСЛЕДУЮТСЯ через `run.extend` —
+ * рукописный форк схемы ЗАПРЕЩЁН (связывающее условие Architect A11): форк молча
+ * ронял бы новые поля `run` из read-контракта, что и есть тот класс дефектов.
+ *
+ * ЗАЧЕМ read/write-асимметрия (docs/12:198): добавление стадии на сервере
+ * (напр. `"publishing"`) сломало бы строгий `run.parse` в `getRun` у КАЖДОГО уже
+ * установленного MCP — неизвестная стадия отверглась бы. Чтение толерантно к
+ * расширению enum стадий; строгость ЗАПИСИ (`run.parse` в `startUgc`) при этом
+ * сохраняется — сервер не должен принимать мусорное тело.
+ */
+export const runRead = run.extend({ state: z.string() });
+/**
+ * Терминален ли ран. Принимает `string` (read-проекция), а не `RunState`,
+ * поэтому неизвестный статус (расширение enum) корректно даёт `false`.
+ */
+export function isTerminal(state) {
+    return TERMINAL_STATES.includes(state);
+}
+//# sourceMappingURL=runs.js.map

package/dist/runs.js.map

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