@clipwright/core 0.1.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Dimantika LLC
+Copyright (c) 2026 Dimantika Sp. z o.o.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/__fixtures__/queue-promises.d.ts

@@ -0,0 +1,87 @@
+/**
+ * ОБЕЩАНИЯ ОЧЕРЕДИ, ЗАПРЕЩЁННЫЕ НА ОТКАЗЕ `account_not_admitted` (US-620).
+ *
+ * ПРАВИЛО (держится чтением; проверка ниже — лишь регрессионный сторож против
+ * уже случавшихся формулировок, см. «что она не гарантирует»). Из 403 известно
+ * ровно одно: у аккаунта нет доступа. Тем же ответом
+ * отвечает аккаунт, у которого доступ СНЯЛИ (третья поверхность вентиля
+ * построена вокруг именно этого случая — `credit-guard.ts`), и обещание скорого
+ * приёма было бы для него ложью в самый неподходящий момент. Поэтому ни одна
+ * поверхность, объясняющая этот отказ, не называет ни срока, ни номера.
+ *
+ * ПОЧЕМУ СПИСОК ОДИН НА ВСЕХ. Правило нарушалось ПЯТЬ раз подряд, и каждый раз
+ * чинилось по адресу находки: совет агенту, `SKILL.md`, тело ответа, снова
+ * совет, публичная дока. Когда сторожей стало двое, список немедленно
+ * разошёлся: у одного было `yet`, у другого — русские корни. Два ответа на
+ * вопрос «что такое это правило» — тот же дефект, который эта же приёмка дважды
+ * признавала блокером (два перечня писателей `admitted_at`, два текста про
+ * очередь). Лечение одно и то же: одна копия, остальные ссылаются.
+ *
+ * ЯЗЫКА ДВА, ПОТОМУ ЧТО КОРПУС ДВУЯЗЫЧНЫЙ. Код и агентские тексты английские,
+ * документация и комментарии русские. Пятое вхождение уцелело ровно потому, что
+ * сторож знал только английский.
+ *
+ * КОРНИ, А НЕ СЛОВОФОРМЫ: `волн` ловит «волну» и «волнами», `очеред` —
+ * «очередь» и «очереди».
+ *
+ * ЧТО ЭТА ПРОВЕРКА НЕ ГАРАНТИРУЕТ, И ЭТО ГЛАВНОЕ ПРО НЕЁ.
+ *
+ * Она НЕ обеспечивает инвариант «не называет срока» — обеспечить смысловой
+ * инвариант списком подстрок невозможно в принципе. «access will be granted
+ * tomorrow», «доступ появится в пятницу», «soon» пройдут: их в списке нет, и
+ * добавить все нельзя — язык не кончается. Обещание, написанное вовсе без имени
+ * отказа, тоже пройдёт: якорь его не найдёт.
+ *
+ * ЧЕГО СПИСОК НЕ ЗНАЕТ, названо поимённо, чтобы следующий автор не полагался на
+ * сторожа там, где тот слеп: `soon`, `shortly`, `waitlist`, `invite`, `batch`,
+ * «скоро», «в ближайшее время», «лист ожидания», «пригласим», «завтра». Все они
+ * пройдут. Добавлять их нельзя: «скоро» и `soon` встречаются в верных текстах
+ * повсюду, и сторож станет шумным — а шумного снимают.
+ *
+ * Что она РЕАЛЬНО делает: не даёт вернуться ШЕСТИ формулировкам, которые в этой
+ * стори уже возвращались — по одной на круг приёмки, в шести разных местах.
+ * Регрессионный сторож против известного класса, а не доказательство свойства.
+ * Само свойство держит чтение: правило и его довод записаны у
+ * `accountNotAdmittedError`, и рецензент, читающий текст отказа, проверяет
+ * смысл, а не подстроки. Считать иначе — значит второй раз поверить, что
+ * зелёный тест равен верному коду.
+ *
+ * ЧЕМ ЭТА ПРОВЕРКА ПЛАТИТ, названо прямо. Подстрочный поиск не отличает
+ * обещание от его отрицания: верная фраза «отказ не ставит аккаунт в очередь»
+ * покраснеет. Это осознанный обмен — сторож ошибается ГРОМКО и чинится
+ * переписыванием фразы, тогда как сторож, разбирающий отрицания, ошибётся ТИХО
+ * и пропустит обещание. Тексты запретов в этом проекте пишутся без запрещаемых
+ * слов; так уже сделано в `SKILL.md` и в `docs/03-api.md`.
+ *
+ * ЛЕЖИТ В `__fixtures__`, а не в публичном экспорте пакета: это тестовый
+ * материал, а не часть контракта клиентов.
+ */
+export declare const QUEUE_PROMISES: readonly ["in waves", "in the queue", "next wave", "yet", "волн", "очеред", "пока что", "подожди"];
+/**
+ * Предмет правила — В НОРМАЛИЗОВАННОМ ВИДЕ, а не одним написанием.
+ *
+ * Скоуп по ИМЕНИ, а не по файлу, проводит границу по смыслу: `CLAUDE.md` вправе
+ * описывать приём волнами как операторский процесс, а `docs/03-api.md` §7 —
+ * очередь рендеров при превышении потолка. Ни то, ни другое не утверждает
+ * ничего про этот 403.
+ *
+ * НО ИМЯ У ПРЕДМЕТА НЕ ОДНО. Кодовая база называет его четырьмя написаниями:
+ * `account_not_admitted` (тело и документы), `accountNotAdmittedBody`
+ * (сборка), `NotAdmittedFailure` (вид отказа) и `kind: "not_admitted"` (вердикт
+ * на четырёх поверхностях). Сторож, знавший только первое, не видел ЧЕТЫРЕХ
+ * файлов, объясняющих тот же отказ, — включая сообщение `issue-token.ts`,
+ * которое читает человек. Обе приёмки нашли это независимо, и это та же форма,
+ * что «список слов английский, а корпус двуязычный»: скоуп по смыслу остаётся
+ * скоупом по написанию, пока опознание однодиалектное.
+ *
+ * Поэтому сравнение идёт по нормализованному тексту: снимаем `_`, приводим к
+ * нижнему регистру, ищем подстроку. Любое БУДУЩЕЕ написание ловится само, без
+ * правки сторожа.
+ *
+ * ЛОЖНЫХ СРАБАТЫВАНИЙ НА СОСЕДЯХ НЕТ, и это проверено, а не предположено:
+ * `already_admitted` (вердикт US-602 «у рана уже есть холд») нормализуется в
+ * `alreadyadmitted` и подстроки `notadmitted` не содержит.
+ */
+export declare const NOT_ADMITTED_ANCHOR = "notadmitted";
+/** Снимает разницу написаний: `account_not_admitted` и `NotAdmittedFailure` — одно. */
+export declare function normalizeForAnchor(text: string): string;

package/dist/__fixtures__/queue-promises.js

@@ -0,0 +1,99 @@
+/**
+ * ОБЕЩАНИЯ ОЧЕРЕДИ, ЗАПРЕЩЁННЫЕ НА ОТКАЗЕ `account_not_admitted` (US-620).
+ *
+ * ПРАВИЛО (держится чтением; проверка ниже — лишь регрессионный сторож против
+ * уже случавшихся формулировок, см. «что она не гарантирует»). Из 403 известно
+ * ровно одно: у аккаунта нет доступа. Тем же ответом
+ * отвечает аккаунт, у которого доступ СНЯЛИ (третья поверхность вентиля
+ * построена вокруг именно этого случая — `credit-guard.ts`), и обещание скорого
+ * приёма было бы для него ложью в самый неподходящий момент. Поэтому ни одна
+ * поверхность, объясняющая этот отказ, не называет ни срока, ни номера.
+ *
+ * ПОЧЕМУ СПИСОК ОДИН НА ВСЕХ. Правило нарушалось ПЯТЬ раз подряд, и каждый раз
+ * чинилось по адресу находки: совет агенту, `SKILL.md`, тело ответа, снова
+ * совет, публичная дока. Когда сторожей стало двое, список немедленно
+ * разошёлся: у одного было `yet`, у другого — русские корни. Два ответа на
+ * вопрос «что такое это правило» — тот же дефект, который эта же приёмка дважды
+ * признавала блокером (два перечня писателей `admitted_at`, два текста про
+ * очередь). Лечение одно и то же: одна копия, остальные ссылаются.
+ *
+ * ЯЗЫКА ДВА, ПОТОМУ ЧТО КОРПУС ДВУЯЗЫЧНЫЙ. Код и агентские тексты английские,
+ * документация и комментарии русские. Пятое вхождение уцелело ровно потому, что
+ * сторож знал только английский.
+ *
+ * КОРНИ, А НЕ СЛОВОФОРМЫ: `волн` ловит «волну» и «волнами», `очеред` —
+ * «очередь» и «очереди».
+ *
+ * ЧТО ЭТА ПРОВЕРКА НЕ ГАРАНТИРУЕТ, И ЭТО ГЛАВНОЕ ПРО НЕЁ.
+ *
+ * Она НЕ обеспечивает инвариант «не называет срока» — обеспечить смысловой
+ * инвариант списком подстрок невозможно в принципе. «access will be granted
+ * tomorrow», «доступ появится в пятницу», «soon» пройдут: их в списке нет, и
+ * добавить все нельзя — язык не кончается. Обещание, написанное вовсе без имени
+ * отказа, тоже пройдёт: якорь его не найдёт.
+ *
+ * ЧЕГО СПИСОК НЕ ЗНАЕТ, названо поимённо, чтобы следующий автор не полагался на
+ * сторожа там, где тот слеп: `soon`, `shortly`, `waitlist`, `invite`, `batch`,
+ * «скоро», «в ближайшее время», «лист ожидания», «пригласим», «завтра». Все они
+ * пройдут. Добавлять их нельзя: «скоро» и `soon` встречаются в верных текстах
+ * повсюду, и сторож станет шумным — а шумного снимают.
+ *
+ * Что она РЕАЛЬНО делает: не даёт вернуться ШЕСТИ формулировкам, которые в этой
+ * стори уже возвращались — по одной на круг приёмки, в шести разных местах.
+ * Регрессионный сторож против известного класса, а не доказательство свойства.
+ * Само свойство держит чтение: правило и его довод записаны у
+ * `accountNotAdmittedError`, и рецензент, читающий текст отказа, проверяет
+ * смысл, а не подстроки. Считать иначе — значит второй раз поверить, что
+ * зелёный тест равен верному коду.
+ *
+ * ЧЕМ ЭТА ПРОВЕРКА ПЛАТИТ, названо прямо. Подстрочный поиск не отличает
+ * обещание от его отрицания: верная фраза «отказ не ставит аккаунт в очередь»
+ * покраснеет. Это осознанный обмен — сторож ошибается ГРОМКО и чинится
+ * переписыванием фразы, тогда как сторож, разбирающий отрицания, ошибётся ТИХО
+ * и пропустит обещание. Тексты запретов в этом проекте пишутся без запрещаемых
+ * слов; так уже сделано в `SKILL.md` и в `docs/03-api.md`.
+ *
+ * ЛЕЖИТ В `__fixtures__`, а не в публичном экспорте пакета: это тестовый
+ * материал, а не часть контракта клиентов.
+ */
+export const QUEUE_PROMISES = [
+    "in waves",
+    "in the queue",
+    "next wave",
+    "yet",
+    "волн",
+    "очеред",
+    "пока что",
+    "подожди",
+];
+/**
+ * Предмет правила — В НОРМАЛИЗОВАННОМ ВИДЕ, а не одним написанием.
+ *
+ * Скоуп по ИМЕНИ, а не по файлу, проводит границу по смыслу: `CLAUDE.md` вправе
+ * описывать приём волнами как операторский процесс, а `docs/03-api.md` §7 —
+ * очередь рендеров при превышении потолка. Ни то, ни другое не утверждает
+ * ничего про этот 403.
+ *
+ * НО ИМЯ У ПРЕДМЕТА НЕ ОДНО. Кодовая база называет его четырьмя написаниями:
+ * `account_not_admitted` (тело и документы), `accountNotAdmittedBody`
+ * (сборка), `NotAdmittedFailure` (вид отказа) и `kind: "not_admitted"` (вердикт
+ * на четырёх поверхностях). Сторож, знавший только первое, не видел ЧЕТЫРЕХ
+ * файлов, объясняющих тот же отказ, — включая сообщение `issue-token.ts`,
+ * которое читает человек. Обе приёмки нашли это независимо, и это та же форма,
+ * что «список слов английский, а корпус двуязычный»: скоуп по смыслу остаётся
+ * скоупом по написанию, пока опознание однодиалектное.
+ *
+ * Поэтому сравнение идёт по нормализованному тексту: снимаем `_`, приводим к
+ * нижнему регистру, ищем подстроку. Любое БУДУЩЕЕ написание ловится само, без
+ * правки сторожа.
+ *
+ * ЛОЖНЫХ СРАБАТЫВАНИЙ НА СОСЕДЯХ НЕТ, и это проверено, а не предположено:
+ * `already_admitted` (вердикт US-602 «у рана уже есть холд») нормализуется в
+ * `alreadyadmitted` и подстроки `notadmitted` не содержит.
+ */
+export const NOT_ADMITTED_ANCHOR = "notadmitted";
+/** Снимает разницу написаний: `account_not_admitted` и `NotAdmittedFailure` — одно. */
+export function normalizeForAnchor(text) {
+    return text.replaceAll("_", "").toLowerCase();
+}
+//# sourceMappingURL=queue-promises.js.map

package/dist/__fixtures__/queue-promises.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue-promises.js","sourceRoot":"","sources":["../../src/__fixtures__/queue-promises.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,UAAU;IACV,cAAc;IACd,WAAW;IACX,KAAK;IACL,MAAM;IACN,QAAQ;IACR,UAAU;IACV,SAAS;CACD,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAC;AAEjD,uFAAuF;AACvF,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AAChD,CAAC"}

package/dist/account.d.ts

@@ -0,0 +1,49 @@
+import { z } from "zod";
+/**
+ * ТЕЛО `GET /v1/account` (US-602).
+ *
+ * ПУТЬ ОБЪЯВЛЕН ДАВНО, ТЕЛО — НЕТ. `docs/03-api.md` обещает этот маршрут с
+ * телом `{plan, credits_balance, renews_at}`. Путь берётся объявленный, тело —
+ * честное: `plan` и `renews_at` мертвы по ADR-012 (тарифных планов и продлений
+ * в продукте нет), и отдавать их означало бы поддерживать поля, за которыми
+ * ничего не стоит. Обещание снимается из документа отдельной стори (US-623).
+ *
+ * ЧЕТЫРЕ ЧИСЛА, А НЕ ОДНО, И КАЖДОЕ ОТВЕЧАЕТ НА СВОЙ ВОПРОС:
+ *  - `balance_credits` — сколько денег есть;
+ *  - `debt_credits` — сколько должен (блокирует новые раны отдельным кодом);
+ *  - `holds_credits` — сколько заморожено под уже идущими ранами;
+ *  - `daily_remaining_credits` — сколько ещё пропустит НАШ суточный
+ *    предохранитель.
+ *
+ * Последнее — НЕ деньги, и потому названо отдельно, а не вычтено из баланса.
+ * Смешай их — и клиент с деньгами на счету, упёршийся в наш операционный
+ * лимит, прочтёт это как «кончились кредиты» и пойдёт покупать ещё. Ровно то
+ * же различение держат два разных кода отказа (`errors.ts`).
+ */
+/**
+ * Начисление. `source` — z.string(), а не enum: перечень источников живёт в
+ * базе и пополняется (промо, партнёрка), а read-контракт обязан переживать
+ * новое значение у уже установленного клиента — та же асимметрия чтения и
+ * записи, что у стадий рана (`runRead`).
+ */
+export declare const creditGrant: z.ZodObject<{
+    amount: z.ZodNumber;
+    source: z.ZodString;
+    expires_at: z.ZodNullable<z.ZodString>;
+    created_at: z.ZodString;
+}, z.core.$strip>;
+export type CreditGrant = z.infer<typeof creditGrant>;
+export declare const account: z.ZodObject<{
+    account_id: z.ZodString;
+    balance_credits: z.ZodNumber;
+    debt_credits: z.ZodNumber;
+    holds_credits: z.ZodNumber;
+    daily_remaining_credits: z.ZodNumber;
+    grants: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        amount: z.ZodNumber;
+        source: z.ZodString;
+        expires_at: z.ZodNullable<z.ZodString>;
+        created_at: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type Account = z.infer<typeof account>;

package/dist/account.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * ТЕЛО `GET /v1/account` (US-602).
+ *
+ * ПУТЬ ОБЪЯВЛЕН ДАВНО, ТЕЛО — НЕТ. `docs/03-api.md` обещает этот маршрут с
+ * телом `{plan, credits_balance, renews_at}`. Путь берётся объявленный, тело —
+ * честное: `plan` и `renews_at` мертвы по ADR-012 (тарифных планов и продлений
+ * в продукте нет), и отдавать их означало бы поддерживать поля, за которыми
+ * ничего не стоит. Обещание снимается из документа отдельной стори (US-623).
+ *
+ * ЧЕТЫРЕ ЧИСЛА, А НЕ ОДНО, И КАЖДОЕ ОТВЕЧАЕТ НА СВОЙ ВОПРОС:
+ *  - `balance_credits` — сколько денег есть;
+ *  - `debt_credits` — сколько должен (блокирует новые раны отдельным кодом);
+ *  - `holds_credits` — сколько заморожено под уже идущими ранами;
+ *  - `daily_remaining_credits` — сколько ещё пропустит НАШ суточный
+ *    предохранитель.
+ *
+ * Последнее — НЕ деньги, и потому названо отдельно, а не вычтено из баланса.
+ * Смешай их — и клиент с деньгами на счету, упёршийся в наш операционный
+ * лимит, прочтёт это как «кончились кредиты» и пойдёт покупать ещё. Ровно то
+ * же различение держат два разных кода отказа (`errors.ts`).
+ */
+/**
+ * Начисление. `source` — z.string(), а не enum: перечень источников живёт в
+ * базе и пополняется (промо, партнёрка), а read-контракт обязан переживать
+ * новое значение у уже установленного клиента — та же асимметрия чтения и
+ * записи, что у стадий рана (`runRead`).
+ */
+export const creditGrant = z.object({
+    amount: z.number().int(),
+    source: z.string(),
+    /** `null` — грант бессрочный. */
+    expires_at: z.string().datetime().nullable(),
+    created_at: z.string().datetime(),
+});
+export const account = z.object({
+    account_id: z.string(),
+    balance_credits: z.number().int().nonnegative(),
+    debt_credits: z.number().int().nonnegative(),
+    holds_credits: z.number().int().nonnegative(),
+    daily_remaining_credits: z.number().int().nonnegative(),
+    /** Только НЕИСТЁКШИЕ: истёкший грант в баланс не входит и в списке не лжёт. */
+    grants: z.array(creditGrant).default([]),
+});
+//# sourceMappingURL=account.js.map

package/dist/account.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.js","sourceRoot":"","sources":["../src/account.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACxB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,iCAAiC;IACjC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC5C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC/C,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC5C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IAC7C,uBAAuB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACvD,+EAA+E;IAC/E,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACzC,CAAC,CAAC"}

package/dist/api-failure.d.ts

@@ -0,0 +1,192 @@
+/**
+ * РАЗБОР ОТКАЗА API — ОДИН НА ВСЕ КЛИЕНТСКИЕ ПОВЕРХНОСТИ (US-622).
+ *
+ * ЧТО БЫЛО. `packages/sdk` сводил ЛЮБОЙ не-2xx к плоскому `new Error(message)`:
+ * ни статуса, ни кода, ни `Retry-After`. Пока API отвечал одними четырёхсотыми
+ * «поле не то», разницы не было — отказ был один, и делать с ним было нечего,
+ * кроме как показать текст. Фаза 1 добавила три кода, с которыми надо
+ * ПОСТУПАТЬ по-разному: 429 — подождать и повторить, 402 — остановиться и
+ * сказать человеку числа, 5xx — повторить без паузы от сервера. Плоский `Error`
+ * делает все три неразличимыми, и клиент выбирает худший вариант из трёх:
+ * первый же 429 на поллинге убивает `makeUgc` целиком.
+ *
+ * ПОЧЕМУ РАЗБОР ЖИВЁТ ЗДЕСЬ, А НЕ В SDK. Поверхностей, читающих отказ, три —
+ * SDK, MCP-форматтер и CLI, — и решение «ретраить или нет» обязано быть у них
+ * общим. Разъедься оно, и MCP советовал бы агенту ждать там, где SDK уже сдался.
+ * Тот же довод, что и у самих схем (правило проекта №2): формы отказов уже
+ * лежат в `errors.ts` и `rate-limit.ts`, здесь — только их РАЗБОР и вывод.
+ *
+ * ЧЕГО ЭТОТ МОДУЛЬ НЕ ДЕЛАЕТ. Он не ходит в сеть и не знает про `fetch`:
+ * вход — статус, текст тела и заголовок. Поэтому его можно прогнать на всех
+ * формах ответа, включая те, которые живой сервер отдать не может, а прокси
+ * между ним и клиентом — вполне (HTML-страница про перегрузку).
+ */
+/** Отказ по частоте: 429 либо наш, либо чужой (прокси, edge тарифа). */
+export interface RateLimitedFailure {
+    kind: "rate_limited";
+    status: number;
+    message: string;
+    /** Через сколько секунд повторять. `undefined` — сервер не сказал. */
+    retryAfterSeconds: number | undefined;
+    /** Потолок ведра. Есть только у НАШЕГО тела; у прокси его нет. */
+    limit: number | undefined;
+    windowSeconds: number | undefined;
+}
+/** Кредитов меньше веса рана. Терминально: повтор не изменит баланс. */
+export interface InsufficientCreditsFailure {
+    kind: "insufficient_credits";
+    status: number;
+    message: string;
+    balanceCredits: number;
+    requiredCredits: number;
+}
+/**
+ * Висит долг. Тоже терминально; лечится покупкой кредитов — поступившие гасят
+ * долг раньше, чем ложатся на баланс (clipwright#27). Отдельным от
+ * `insufficient_credits` отказ остаётся из-за разного положения дел: с долгом
+ * баланс бывает ненулевым.
+ */
+export interface DebtOutstandingFailure {
+    kind: "debt_outstanding";
+    status: number;
+    message: string;
+    debtCredits: number;
+}
+/**
+ * Аккаунт не допущен в бету (US-620). Терминально, и лечится НЕ деньгами.
+ *
+ * Отдельный вид, а не `client_error` с кодом: у `client_error` совет агенту —
+ * «поправь вызов», а поправить в вызове нечего. Разница видна человеку: ему
+ * надо сказать «доступ выдаёт владелец», а не «ты что-то не так передал» и не
+ * «купи кредитов».
+ */
+export interface NotAdmittedFailure {
+    kind: "not_admitted";
+    status: number;
+    message: string;
+}
+/** 5xx: сервер обещает, что дело в нём. Повторять можно. */
+export interface ServerFailure {
+    kind: "server_error";
+    status: number;
+    message: string;
+    retryAfterSeconds: number | undefined;
+}
+/** Всё остальное (4xx): повтор того же запроса даст то же самое. */
+export interface ClientFailure {
+    kind: "client_error";
+    status: number;
+    message: string;
+    /** Код из тела, если тело вообще было контрактным. */
+    code: string | undefined;
+}
+export type ApiFailure = RateLimitedFailure | InsufficientCreditsFailure | DebtOutstandingFailure | NotAdmittedFailure | ServerFailure | ClientFailure;
+/**
+ * ПОВТОРЯТЬ ИЛИ НЕТ — ОДНОЙ ФУНКЦИЕЙ, а не условием на каждой поверхности.
+ *
+ * Ошибиться здесь можно в обе стороны, и цены разные. Не повторить 429 — это
+ * оборванный `makeUgc` на ране, за который уже заплачено. Повторить 402 — это
+ * агент, крутящий отказ по деньгам в цикле: баланс от повторов не растёт, а
+ * лимит частоты они съедают, и человек получает вместо «пополни счёт» молчание
+ * до самого дедлайна.
+ */
+export declare function isRetryableFailure(failure: ApiFailure): boolean;
+/**
+ * Пауза перед повтором, мс. `fallbackMs` — собственный шаг вызывателя (для
+ * поллинга это его интервал): он же и пол, потому что сервер, не назвавший
+ * `Retry-After`, не разрешил долбить чаще обычного.
+ *
+ * Вызывать имеет смысл только после `isRetryableFailure`; на терминальном
+ * отказе результат бессмыслен, и функция не притворяется, что это не так.
+ */
+export declare function retryDelayMs(failure: ApiFailure, fallbackMs: number): number;
+/**
+ * `Retry-After` в секундах, обе формы RFC 9110.
+ *
+ * ДВЕ ФОРМЫ — НЕ ПЕДАНТИЗМ. Дельту в секундах отдаёт наша мидлвара, а HTTP-дату
+ * — чужие прокси (её разрешает та же RFC, и nginx с облачными edge её ставят).
+ * Клиент, знающий только цифры, на дате получил бы `NaN` и либо не ждал вовсе,
+ * либо ждал бесконечность — обе ветки хуже, чем «подожди свой обычный шаг».
+ *
+ * `now` — параметр, а не `Date.now()` внутри: разбор даты обязан быть проверяем
+ * прогоном, а не зависеть от того, когда его запустили.
+ */
+export declare function parseRetryAfterSeconds(raw: string | null | undefined, now: Date): number | undefined;
+export interface ApiFailureInput {
+    status: number;
+    /**
+     * Сырой текст тела. Именно текст: `res.json()` на HTML бросает парсером.
+     *
+     * `undefined` — тело ПРОЧИТАТЬ НЕ УДАЛОСЬ (соединение оборвалось после
+     * заголовков). Это НЕ то же самое, что пустое или чужое тело, и путать их
+     * нельзя: по пустой строке нельзя судить, кто ответил (внешнее ревью, круг 13).
+     */
+    bodyText: string | undefined;
+    /** Значение заголовка `Retry-After`, как его отдал сервер. */
+    retryAfterHeader?: string | null | undefined;
+    /** Точка отсчёта для формы HTTP-date. */
+    now?: Date;
+}
+/**
+ * Статус + тело + заголовок → то, с чем можно ПОСТУПИТЬ.
+ *
+ * ТЕЛО УТОЧНЯЕТ СТАТУС, НО НЕ ОТМЕНЯЕТ ЕГО. Специализированная схема
+ * применяется, только если статус ей СООТВЕТСТВУЕТ: `rate_limited` — на 429,
+ * оба денежных кода — на 402.
+ *
+ * Первая редакция давала телу перевешивать статус, рассуждая так: код объявлен
+ * в теле, а статус по дороге переписывает кто угодно, значит 502 поверх нашего
+ * 402 — это всё ещё «не хватило кредитов». Внешнее ревью показало обратную
+ * сторону того же рассуждения, и она хуже. Кэширующий прокси, отдавший старое
+ * тело `debt_outstanding` с новым статусом 429, делал отказ ТЕРМИНАЛЬНЫМ: агент
+ * бросал бы уже оплаченный ран и требовал погасить долг, которого нет. Зеркально
+ * 402 с телом `rate_limited` становился РЕТРАЙНЫМ, прямо вопреки правилу «любой
+ * 402 останавливает». Получались и внутренне противоречивые отказы вида
+ * `status === 402 && retryable === true`.
+ *
+ * Сочетание статуса и кода из РАЗНЫХ ответов — это не сообщение, а его порча, и
+ * доверять в нём надо тому, что уцелело наверняка. Уцелел статус: он часть
+ * стартовой строки, его не кэшируют отдельно от тела и им управляет тот же
+ * узел, который решил ответить. Поэтому при расхождении класс отказа берётся из
+ * статуса, а текст — из тела: сказать «сервер перегружен, повтори» и оказаться
+ * неправым дешевле, чем бросить оплаченный ран.
+ *
+ * ЧИСЛА `retry_after_seconds` ИЗ ТЕЛА СИЛЬНЕЕ ЗАГОЛОВКА — здесь тело выигрывает
+ * законно, потому что спорят два поля ОДНОГО ответа, а не ответ с самим собой.
+ * Наша мидлвара ставит в оба места одно число, и заголовок переписывают чаще.
+ */
+export declare function parseApiFailure(input: ApiFailureInput): ApiFailure;
+/**
+ * ОТКАЗ, РАЗВЁРНУТЫЙ ДЛЯ АГЕНТА, — ОДНОЙ ФУНКЦИЕЙ НА ВСЕ ПОВЕРХНОСТИ (US-622).
+ *
+ * ПОЧЕМУ НЕ «ПРОСТО ТЕКСТ ОШИБКИ». Отказ по деньгам — это не сбой, а РАЗВИЛКА,
+ * и агент обязан её пройти, а не ретраить: 402 повторами не лечится, баланс от
+ * них не растёт. Значит ответ обязан нести три вещи, которых в строке нет:
+ * числа (сколько есть, сколько нужно), императив («останови и скажи человеку»)
+ * и признак, что повторять бессмысленно. Форма скопирована с `next_action` из
+ * ADR-009 ровно потому, что она уже работает: `make_ugc` и `get_run` говорят с
+ * агентом так же, и отказ, говорящий иначе, читался бы как другой продукт.
+ *
+ * ПОЧЕМУ ЗДЕСЬ, А НЕ В MCP-ФОРМАТТЕРЕ. Поверхностей три, и разъехаться им
+ * нельзя: MCP отдаёт этот объект агенту, CLI печатает те же числа человеку, а
+ * SDK держит их в типизированной ошибке. Собери форму в MCP — и CLI пришлось бы
+ * собирать её ВТОРОЙ раз, то есть завести второй источник правды о том, что
+ * значит отказ (правило проекта №2).
+ */
+export interface AgentFailureReport {
+    /** Императив: повторять этот же вызов позже или прекратить. */
+    status: "RETRY_LATER" | "FAILED";
+    /** Машиночитаемая причина. Для чужих тел — `http_<status>`. */
+    code: string;
+    message: string;
+    /** Дубль `status` для условия в коде: строку легко сравнить неверно. */
+    retryable: boolean;
+    next_action: string;
+    retry_after_seconds?: number;
+    limit?: number;
+    window_seconds?: number;
+    balance_credits?: number;
+    required_credits?: number;
+    debt_credits?: number;
+}
+export declare function agentFailureReport(failure: ApiFailure): AgentFailureReport;