@besales/mcp 0.48.0 → 1.0.0-beta.2

package/scripts/emit-tool-routes.mjs

@@ -0,0 +1,878 @@
+// Выгружает в besales-api перечисление инструментов и адрес каждого — вход проверки полноты моста.
+//
+// ⭐ Перечисление ведётся от ОТГРУЖЕННОГО реестра по общей настройке ссылки, а не от ветки v2. Пока входом
+// была ветка v2, проверка сравнивала v2 сам с собой: инструмент, отгруженный клиенту, но
+// отсутствующий в v2, не видел ни один гвард.
+//
+// Адрес и тело выводятся ПРОГОНОМ `createRequest` на аргументах, выведенных из отгруженной схемы, —
+// рукописный список разъехался бы с кодом ровно так же, как разъехались карты.
+import { execFileSync } from 'node:child_process';
+import { readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { routeLagFindings } from './route-lag.mjs';
+import { remainingLagSections } from './lag-payload.mjs';
+
+import { extractConnectScopes } from './connect-scopes.mjs';
+import { collectInputSchemas, namesWithoutSchema } from './tool-input-schemas.mjs';
+import { SHIPPED_INPUT_PATHS, loadShippedRegistry } from './shipped-registry.mjs';
+import { loadShippedDefinitions } from './shipped-definitions.mjs';
+import {
+  buildShippedSample,
+  filterOf,
+  prepareKnownArgs,
+  resolveShippedVariant,
+  routeShape,
+  schemaLagExplains,
+  schemaPathsOf,
+  valuesAt,
+  variantExtensionFindings,
+  withGeneratedValues,
+  withValueAt,
+} from './shipped-sample.mjs';
+import { diffRegistries, lagKey, reconcileWithRegistry } from './registry-diff.mjs';
+import { resetSampleUid, sampleFor } from './sample-args.mjs';
+import { hasExactRefusalPath } from './refusal-probe.mjs';
+import { SHIPPED_SAMPLE_FALLBACKS, shippedSampleCandidates } from './shipped-sample-candidates.mjs';
+import { parseQuery, shippedQueryCarrierSample } from './request-query.mjs';
+import { lagOpenTaskErrors, readLagPlans } from './lag-open-task-owners.mjs';
+
+const CONTRACTS_DIR_ENV = 'BESALES_API_CONTRACTS_DIR';
+const packageRoot = new URL('..', import.meta.url).pathname;
+
+const contractsDir = process.env[CONTRACTS_DIR_ENV]?.trim();
+if (!contractsDir) {
+  // Каталог назначения обязателен: скрипт живёт в общем репозитории пакета, а besales-api бывает
+  // разложен несколькими рабочими деревьями. Вычисленный «по соседству» путь молча писал бы в чужую
+  // ветку — правка уезжала бы туда, где её никто не ждёт.
+  console.error(
+    `Не задан ${CONTRACTS_DIR_ENV} — каталог contracts/ целевого besales-api. ` +
+      'Пример: BESALES_API_CONTRACTS_DIR=../besales-api/contracts yarn publish:mcp-registry',
+  );
+  process.exit(1);
+}
+const OUT = resolve(contractsDir, 'mcp-tool-routes.json');
+// Диагностика не является подписанной выгрузкой: только файловый эталон и
+// временное назначение. Штатный путь сохраняет все проверки происхождения.
+const dryRun = process.argv.includes('--dry-run');
+if (
+  dryRun &&
+  (!process.env.BESALES_MCP_SHIPPED_REGISTRY?.trim() ||
+    !realpathSync(contractsDir)
+      .split('/')
+      .some((part) => /^\.codex-artifacts-[A-Za-z0-9_-]+$/u.test(part)))
+) {
+  throw new Error(
+    '--dry-run требует файловый эталон и contracts/ внутри .codex-artifacts-*/',
+  );
+}
+// Рабочая область у сгенерированного набора одна и та же: она не участвует в различении веток.
+const SAMPLE_WORKSPACE_ID = '00000000-0000-4000-8000-0000000000ff';
+// Третий вход выгрузки на отгружаемой линии: исходник клиента, из которого извлекаются права
+// подключения. Объявлен константой, потому что уезжает в выгрузку вместе с двумя из загрузчика —
+// по этому списку besales-api считает СВЕЖЕСТЬ артефакта.
+const SHIPPED_CLIENT_SOURCE = 'src/auth/oauth-client.ts';
+
+const { toolDefinitions } = await import('../dist/tools/definitions.js');
+const localRegistry = JSON.parse(
+  readFileSync(new URL('../src/schemas/mcp-tools.json', import.meta.url), 'utf8'),
+);
+const lagRegistry = JSON.parse(
+  readFileSync(new URL('../src/schemas/shipped-lag.json', import.meta.url), 'utf8'),
+);
+const metadataErrors = lagOpenTaskErrors(lagRegistry, readLagPlans());
+if (metadataErrors.length > 0) {
+  throw new Error(`Некорректные владельцы/метаданные отставания:\n${metadataErrors.join('\n')}`);
+}
+// ⛔ Выгрузка подписывается коммитом HEAD, а инструменты берутся из рабочей сборки: при незакоммиченных правках подпись
+// называла бы коммит, из которого выгрузка НЕ собрана. Поэтому незакоммиченное дерево — отказ выгрузки.
+const uncommitted = execFileSync('git', ['-C', packageRoot, 'status', '--porcelain'], {
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe'],
+}).trim();
+if (uncommitted !== '' && !dryRun) {
+  console.error(
+    'Дерево моста не закоммичено: выгрузка подписывается коммитом HEAD, а инструменты берутся из рабочей сборки. ' +
+      `Закоммитьте правки и перевыпустите:\n${uncommitted}`,
+  );
+  process.exit(1);
+}
+const shipped = loadShippedRegistry(packageRoot);
+// Права подключения отгруженного клиента — из того же коммита эталона, что и реестр инструментов. Файловый вход
+// эталона коммита для чтения исходника не даёт. Диагностика ниже сверяет файл с названным git-коммитом;
+// штатная выгрузка по-прежнему принимает только обновлённый git-эталон.
+if (shipped.provenance.source !== 'git' && !dryRun) {
+  console.error(
+    'Права подключения выгружаются только из git-эталона: файловый вход исходника клиента не содержит',
+  );
+  process.exit(1);
+}
+if (dryRun) {
+  const committedRegistry = execFileSync(
+    'git',
+    [
+      '-C',
+      packageRoot,
+      'show',
+      `${shipped.provenance.commit}:src/schemas/mcp-tools.json`,
+    ],
+    { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 },
+  );
+  if (
+    JSON.stringify(JSON.parse(committedRegistry).tools) !==
+    JSON.stringify(shipped.tools)
+  ) {
+    throw new Error(
+      'Файловый эталон не совпадает с названным коммитом отгруженной линии',
+    );
+  }
+  console.warn(
+    'ДИАГНОСТИКА: source=file, без fetch; результат не пригоден для коммита',
+  );
+  shipped.provenance.diagnosticOnly = true;
+}
+const connectScopes = {
+  source: SHIPPED_CLIENT_SOURCE,
+  commit: shipped.provenance.commit,
+  scopes: extractConnectScopes(
+    execFileSync(
+      'git',
+      ['-C', packageRoot, 'show', `${shipped.provenance.commit}:${SHIPPED_CLIENT_SOURCE}`],
+      {
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    ),
+  ),
+};
+// Права, которые запрашивает ЭТА ветка (v2), — тем же извлекателем и с коммита, на котором стоит генератор. Сервер
+// обязан принять и их: клиент, выпущенный с этой ветки, иначе не подключится. Берётся закоммиченный текст, а не
+// рабочий файл: коммит в выгрузке обязан называть ровно то, из чего извлечён набор.
+const generatorV2Commit = execFileSync('git', ['-C', packageRoot, 'rev-parse', 'HEAD'], {
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'pipe'],
+}).trim();
+const v2ConnectScopes = {
+  source: 'src/auth/oauth-client.ts',
+  commit: generatorV2Commit,
+  scopes: extractConnectScopes(
+    execFileSync(
+      'git',
+      ['-C', packageRoot, 'show', `${generatorV2Commit}:src/auth/oauth-client.ts`],
+      {
+        encoding: 'utf8',
+        maxBuffer: 16 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      },
+    ),
+  ),
+};
+// Отгруженные определения ИСПОЛНЯЮТСЯ: образец отгруженного вызова обязан пройти фильтр отгруженного инструмента
+// (см. `shipped-sample.mjs`). Сбой загрузки — отказ выгрузки целиком, а не причина отдельного случая.
+const shippedDefinitions = await loadShippedDefinitions(packageRoot, shipped.provenance.commit);
+const shippedDefinitionByName = new Map(
+  shippedDefinitions.toolDefinitions.map((definition) => [definition.name, definition]),
+);
+const shippedSchemas = new Map(shipped.tools.map((tool) => [tool.name, tool.inputSchema]));
+const shippedNameBySuccessor = new Map(
+  Object.entries(lagRegistry.toolSuccessors ?? {}).map(([shippedName, v2Name]) => [
+    v2Name,
+    shippedName,
+  ]),
+);
+const localSchemas = new Map(localRegistry.tools.map((tool) => [tool.name, tool.inputSchema]));
+
+// Аргументы из карты маршрутов предпочтительнее сгенерированных: они проверены тестом и, в отличие
+// от генерации, проходят там, где схема требует ровно одно из взаимоисключающих полей.
+const routeMap = JSON.parse(
+  readFileSync(new URL('../src/schemas/mcp-v2-route-map.json', import.meta.url), 'utf8'),
+);
+const routeLagProblems = routeLagFindings(
+  routeMap,
+  lagRegistry.routeLag ?? {},
+  readFileSync(new URL('../src/types/api-contract.gen.ts', import.meta.url), 'utf8'),
+);
+if (routeLagProblems.length > 0) throw new Error(routeLagProblems.join('\n'));
+// Из этих аргументов выводятся тело и строка запроса, которые besales-api прогоняет через настоящий
+// вход маршрута.
+//
+// ⭐ Ветвящийся инструмент выгружается ПО ЗАПИСИ НА ВАРИАНТ (2026-08-11, кусок A задачи 6.6.6).
+//
+// Прежде выгружался ровно один вариант — тот, что оказался в фикстуре первым. Это молча оставляло
+// без проверки вторые ветки семи инструментов, причём у части из них ветки ведут в РАЗНЫЕ адреса и
+// методы (правка правила маршрутизации: PATCH против POST). Промежуточная попытка «выбирать самый
+// богатый набор» была сделана и ОТКАЧЕНА: она не убирает зависимость от порядка, не видит разницы
+// во вложенных полях и замеренно ослабила стража — у статистики шагов выбор переключился на вариант
+// с моментом времени вместо календарной даты отгруженной схемы.
+//
+// Восьмую ветку — создание цепочки дожимов против её правки — нашла не рукопись, а выводимая
+// проверка полноты в `v2-route-map.spec.ts`: она прогоняет конструктор с одним снятым или
+// добавленным необязательным полем и требует, чтобы объявленных веток было не меньше числа
+// различимых пар «метод + форма адреса».
+// ⛔ Инструмент БЕЗ строки фикстуры (таких 26: ICP, песочница, промпт-операции, каталог моделей,
+// оба инструмента аналитики) обязан остаться в выгрузке. Поэтому список вариантов у него — один
+// БЕЗЫМЯННЫЙ элемент, а не пустота: наивный цикл «по вариантам фикстуры» выкинул бы их молча.
+const variantsByTool = new Map();
+for (const entry of routeMap) {
+  const [name, variant] = splitVariantKey(entry.tool);
+  if (!variantsByTool.has(name)) variantsByTool.set(name, []);
+  variantsByTool.get(name).push({ variant, args: entry.canonicalArgs });
+}
+
+// ⛔ Помощники ниже НЕ экспортируются намеренно. Модуль сразу пишет артефакт и умеет завершить
+// процесс кодом 1, поэтому импортировать его ради одной функции нельзя — экспорт обещал бы
+// переиспользование, которого нет.
+
+/** Ключ пары для сообщений об ошибке: без варианта — голое имя. */
+function variantKey(name, variant) {
+  return variant === undefined ? name : name + '@' + variant;
+}
+
+/** Разбор ключа фикстуры `инструмент@вариант`. Безвариантный ключ даёт `undefined`. */
+function splitVariantKey(key) {
+  const at = key.indexOf('@');
+  return at === -1 ? [key, undefined] : [key.slice(0, at), key.slice(at + 1)];
+}
+
+/**
+ * Варианты инструмента в порядке строк фикстуры.
+ *
+ * ⛔ Порядок несущий: по нему считаются идентификаторы образцов, и «побайтово прежние записи» —
+ * обещание, у которого без фиксированного порядка нет носителя.
+ */
+function variantsOf(name, map) {
+  return map.get(name) ?? [{ variant: undefined, args: undefined }];
+}
+
+/**
+ * Аргументы, которыми проверяется совместимость с ОТГРУЖЕННЫМ клиентом.
+ *
+ * Голый образец по отгруженной схеме не годится: схема инструмента слабее доменных ограничений
+ * маршрута (только цифры, перечисление транспортов), и такой набор давал бы ложный отказ вместо
+ * находки. Проверенные `canonicalArgs` — наоборот, беднее отгруженного входа и не трогают поля,
+ * ради которых всё затевалось. Поэтому берётся образец отгруженной схемы, а поверх него кладутся
+ * проверенные значения: доменно-корректные значения побеждают, отгруженные поля добавляются.
+ */
+function mergeShippedArgs(sampled, known) {
+  if (Array.isArray(known)) {
+    if (!Array.isArray(sampled) || sampled.length === 0) return known;
+    return known.map((item) => mergeShippedArgs(sampled[0], item));
+  }
+  if (known === null || typeof known !== 'object') return known;
+  if (sampled === null || typeof sampled !== 'object' || Array.isArray(sampled)) return known;
+  const out = { ...sampled };
+  for (const [key, value] of Object.entries(known))
+    out[key] = mergeShippedArgs(sampled[key], value);
+  return out;
+}
+
+// ⛔ Сверка с реестром отставания идёт ПОСЛЕ образцов: отказ ветки v2, живущий в коде инструмента, виден только
+// исполнением образца, и сверяется он вместе с расхождениями схем — по объединению (строки `…#refused`).
+const diff = diffRegistries(shipped.tools, localRegistry.tools, lagRegistry.toolSuccessors);
+
+const tools = [];
+const failed = [];
+/** Наблюдённые отказы v2 на законных отгруженных вызовах: `инструмент → путь → тип поля у отгруженного`. */
+const observedRefusals = new Map();
+/** Находки образцов, при которых выгрузка не пишется. */
+const sampleFindings = [];
+const usedShippedSampleFallbacks = new Set();
+for (const definition of toolDefinitions) {
+  if (typeof definition.createRequest !== 'function') {
+    tools.push({ name: definition.name, kind: 'local' });
+    continue;
+  }
+  for (const knownVariant of variantsOf(definition.name, variantsByTool)) {
+    emitVariant(definition, knownVariant);
+  }
+}
+
+/**
+ * Ужесточения, которых нет в JSON Schema: голый null и доменные пределы из текста описания.
+ * Каждая проба сначала подтверждает законную соседнюю форму, затем отказ именно по этому пути.
+ * Если фильтр перестал отказывать, выгрузка падает и строка реестра должна быть снята.
+ */
+const stricterInputProbes = [
+  ...['document', 'qa', 'table', 'website'].map((kind) => [
+    `besales_knowledge_${kind}_list`,
+    'page',
+    { knowledge_space_id: '00000000-0000-4000-8000-000000000002' },
+    { knowledge_space_id: '00000000-0000-4000-8000-000000000002', page: 2 },
+    'integer',
+    true,
+  ]),
+  [
+    'besales_platform_settings_update',
+    'widget_marketing.web_widget_customization',
+    { widget_marketing: { web_widget_customization: {} } },
+    { widget_marketing: { web_widget_customization: null } },
+    'null',
+  ],
+  [
+    'besales_platform_settings_update',
+    'widget_marketing.web_widget_marketing_field_mappings',
+    { widget_marketing: { web_widget_marketing_field_mappings: {} } },
+    { widget_marketing: { web_widget_marketing_field_mappings: null } },
+    'null',
+  ],
+  [
+    'besales_platform_settings_update',
+    'widget_marketing.web_widget_entry_url_variable_mapping',
+    { widget_marketing: { web_widget_entry_url_variable_mapping: {} } },
+    { widget_marketing: { web_widget_entry_url_variable_mapping: null } },
+    'null',
+  ],
+  [
+    'besales_behavior_update',
+    'message_filters[].source',
+    {
+      message_filters: [{ id: 'x', source: 'а', target: 'б', enabled: true, order: 1 }],
+    },
+    {
+      message_filters: [
+        {
+          id: 'x',
+          source: '\uFDD0',
+          target: 'б',
+          enabled: true,
+          order: 1,
+        },
+      ],
+    },
+    'string',
+  ],
+  [
+    'besales_behavior_update',
+    'message_filters[].source',
+    {
+      message_filters: [{ id: 'x', source: 'а', target: 'б', enabled: true, order: 1 }],
+    },
+    {
+      message_filters: [{ id: 'x', source: '', target: 'б', enabled: true, order: 1 }],
+    },
+    'string',
+  ],
+  [
+    'besales_behavior_update',
+    'message_filters[].target',
+    {
+      message_filters: [{ id: 'x', source: 'а', target: 'б', enabled: true, order: 1 }],
+    },
+    {
+      message_filters: [
+        {
+          id: 'x',
+          source: 'а',
+          target: '\uFDD1',
+          enabled: true,
+          order: 1,
+        },
+      ],
+    },
+    'string',
+  ],
+  [
+    'besales_behavior_update',
+    'error_handling.ai_error_target_stage_id',
+    { error_handling: { ai_error_target_stage_id: 0 } },
+    { error_handling: { ai_error_target_stage_id: -1 } },
+    'integer',
+  ],
+];
+for (const [
+  name,
+  path,
+  good,
+  bad,
+  shippedType,
+  nonnegativeInteger = false,
+] of stricterInputProbes) {
+  const definition = toolDefinitions.find((item) => item.name === name);
+  const shippedDefinition = shippedDefinitionByName.get(name);
+  const schema = shippedSchemas.get(name);
+  const shippedPath =
+    schema === undefined ? undefined : schemaPathsOf(schema, `отгруженный ${name}`).get(path);
+  if (definition === undefined || shippedDefinition === undefined || shippedPath === undefined) {
+    sampleFindings.push(`${name}::${path}: нет определения или поля отгруженного реестра`);
+    continue;
+  }
+  const declaredTypes = Array.isArray(shippedPath.type) ? shippedPath.type : [shippedPath.type];
+  const declaredAllows =
+    declaredTypes.includes(shippedType) &&
+    (shippedType !== 'string' ||
+      shippedPath.maxLength === undefined ||
+      shippedPath.maxLength >= 51) &&
+    (shippedType !== 'integer' ||
+      nonnegativeInteger ||
+      shippedPath.minimum === undefined ||
+      shippedPath.minimum < 0);
+  if (!declaredAllows) {
+    sampleFindings.push(`${name}::${path}: отгруженный реестр уже ограничивает пробное значение`);
+    continue;
+  }
+  const accept = filterOf(definition, SAMPLE_WORKSPACE_ID);
+  const base = { platform_id: '00000000-0000-4000-8000-000000000002' };
+  const baseline = accept({ ...base, ...good });
+  const rejected = accept({ ...base, ...bad });
+  const shippedAccepted = filterOf(shippedDefinition, SAMPLE_WORKSPACE_ID)({ ...base, ...bad });
+  const hasPath = hasExactRefusalPath(rejected, path);
+  if (!baseline.ok || !hasPath || !shippedAccepted.ok) {
+    sampleFindings.push(
+      `${name}::${path}: проба не подтвердила приём отгруженной линией и адресный отказ v2`,
+    );
+    continue;
+  }
+  if (!observedRefusals.has(name)) observedRefusals.set(name, new Map());
+  observedRefusals.get(name).set(path, shippedType);
+}
+
+/**
+ * Одна запись артефакта: пара «инструмент × вариант».
+ *
+ * ⛔ Поле `variant` у безвариантного инструмента физически НЕ сериализуется. Только так 180 записей
+ * из 187 остаются побайтово прежними, и правка одного ветвящегося инструмента не краснит сравнение
+ * у всех остальных.
+ */
+function emitVariant(definition, knownVariant) {
+  resetSampleUid();
+  const knownArgsForVariant = knownVariant.args;
+  // Часть инструментов отвергает отдельные ветки входа ДО HTTP (взаимоисключающие поля,
+  // неподдержанные в v2 параметры). Поэтому перебираем наборы аргументов целиком — вместе с
+  // прогоном конструктора: максимальный набор у таких инструментов заведомо упирается в отказ,
+  // а обязательный минимум проходит. Первым идёт набор, выведенный из ОТГРУЖЕННОЙ схемы: тело
+  // выгрузки должно отражать вызов клиента, а не удобную для нас форму.
+  const shippedSchema = shippedSchemas.get(
+    shippedNameBySuccessor.get(definition.name) ?? definition.name,
+  );
+  const localSchema = localSchemas.get(definition.name);
+  let request = null;
+  let bodySource = null;
+  // Проверенные аргументы карты идут ПЕРВЫМИ: сгенерированный по JSON-схеме набор проходит саму
+  // схему, но не доменные ограничения принимающей стороны (только цифры, перечисление транспортов),
+  // и выведенное из него тело давало бы ложный отказ вместо находки.
+  const candidates = [
+    ...(knownArgsForVariant === undefined
+      ? []
+      : [{ args: knownArgsForVariant, source: 'canonicalArgs' }]),
+    ...(shippedSchema
+      ? [
+          {
+            args: sampleFor(definition.name, shippedSchema, false),
+            source: 'generated',
+          },
+        ]
+      : []),
+    {
+      args: sampleFor(definition.name, localSchema, false),
+      source: 'generated',
+    },
+    ...(shippedSchema
+      ? [
+          {
+            args: sampleFor(definition.name, shippedSchema, true),
+            source: 'generated',
+          },
+        ]
+      : []),
+    {
+      args: sampleFor(definition.name, localSchema, true),
+      source: 'generated',
+    },
+  ];
+  for (const candidate of candidates) {
+    try {
+      let input = definition.schema.parse(candidate.args);
+      if (definition.defaultWorkspaceId && input.workspace_id === undefined) {
+        input = definition.schema.parse({
+          ...input,
+          workspace_id: SAMPLE_WORKSPACE_ID,
+        });
+      }
+      request = definition.createRequest(input);
+      bodySource = candidate.source;
+      break;
+    } catch {
+      request = null;
+    }
+  }
+  if (request === null) {
+    // Ни один сгенерированный набор не дошёл до запроса — это дефект схемы инструмента,
+    // а не повод промолчать и выгрузить неполный список.
+    failed.push(variantKey(definition.name, knownVariant.variant));
+    return;
+  }
+  // Второе тело — ЗАКОННЫЙ вызов отгруженного клиента (он прошёл отгруженный фильтр) и ответ ветки v2 на него. Именно
+  // оно отвечает на вопрос задачи: примет ли v2-DTO то, что шлёт клиент, стоящий у людей сейчас.
+  // ⛔ Пропажу отгруженного образца нельзя выражать ОТСУТСТВИЕМ поля: «у инструмента нет отгруженного двойника» и
+  // «образец невозможен» выглядели бы одинаково. Невозможность выгружается причиной из закрытого перечня.
+  const shippedSample =
+    shippedSchema !== undefined
+      ? shippedSampleFor(definition, knownVariant, shippedSchema, localSchema, request)
+      : undefined;
+  const shippedRequest = shippedSample?.request;
+  const shippedBody = shippedRequest?.body;
+  const sampleQuery = parseQuery(request.path);
+  // GET без параметров тоже является собранным отгруженным вызовом. Пустой объект сохраняет
+  // его фактическую форму и даёт серверному сторожу прогнать именно пустую строку запроса через DTO.
+  // Иначе v2 с limit/cursor выглядел как инструмент вообще без отгруженного образца.
+  const shippedCarrier = shippedQueryCarrierSample(shippedSample);
+
+  // Строка запроса выгружается ВСЕГДА, когда она есть: у инструмента без отгруженного двойника
+  // (новый в v2) её иначе не было бы вовсе — а это ровно тот класс, где карту писала одна рука и
+  // страж нужнее всего. Отсутствие поля означает «запроса нет», а не «вывести не удалось».
+  tools.push({
+    name: definition.name,
+    ...(knownVariant.variant === undefined ? {} : { variant: knownVariant.variant }),
+    kind: 'api',
+    method: request.method ?? 'POST',
+    samplePath: request.path.split('?')[0],
+    ...(sampleQuery === undefined ? {} : { sampleQuery }),
+    ...(request.body === undefined ? {} : { sampleBody: request.body, bodySource }),
+    ...(shippedBody === undefined ? {} : { shippedSampleBody: shippedBody }),
+    ...shippedCarrier,
+    ...(shippedSample?.omitted.length ? { shippedSampleOmitted: shippedSample.omitted } : {}),
+    ...(shippedSample?.alternatives.length
+      ? {
+          shippedSampleAlternatives: shippedSample.alternatives.map(alternativeRecord),
+        }
+      : {}),
+    ...(shippedSample?.impossible === undefined
+      ? {}
+      : {
+          shippedRequestFailed: true,
+          shippedSampleImpossible: shippedSample.impossible,
+        }),
+  });
+}
+
+/** Запись альтернативы: путь, ради которого она собрана, адрес и тело или строка запроса. */
+function alternativeRecord(alternative) {
+  const query = parseQuery(alternative.request.path);
+  return {
+    forPath: alternative.forPath,
+    method: alternative.request.method ?? 'POST',
+    samplePath: alternative.request.path.split('?')[0],
+    ...(query === undefined ? {} : { query }),
+    ...(alternative.request.body === undefined ? {} : { body: alternative.request.body }),
+    ...(alternative.omitted.length > 0 ? { omitted: alternative.omitted } : {}),
+  };
+}
+
+/** Один и тот же маршрут: метод и адрес без строки запроса, идентификаторы в адресе не различаются. */
+function sameRoute(left, right) {
+  return routeShape(left) === routeShape(right);
+}
+
+/**
+ * Образец отгруженного вызова варианта (см. `shipped-sample.mjs`): шаг 0 — проверенные аргументы без полей, которых
+ * у отгруженного нет; затем перебор. Не нашёлся законный набор, а проверенное значение нарушает объявленное
+ * ограничение отгруженной схемы, — повтор со значением генератора на этих путях; повтор годится, только если ведёт в
+ * ТОТ ЖЕ маршрут: иначе проверенное значение и задавало вариант, и такой формы у отгруженного клиента нет.
+ */
+function shippedSampleFor(definition, knownVariant, shippedSchema, localSchema, mainRequest) {
+  const shippedName = shippedNameBySuccessor.get(definition.name) ?? definition.name;
+  const shippedDefinition = shippedDefinitionByName.get(shippedName);
+  const key = variantKey(definition.name, knownVariant.variant);
+  if (shippedDefinition === undefined || typeof shippedDefinition.createRequest !== 'function') {
+    return {
+      omitted: [],
+      alternatives: [],
+      impossible: { reason: 'SHIPPED_DEFINITION_UNAVAILABLE', paths: [] },
+    };
+  }
+  const schemaLag = diff.contractLag.filter((row) => row.tool === shippedName);
+  const shippedPaths = schemaPathsOf(shippedSchema, `отгруженный ${shippedName}`);
+  const v2Paths = schemaPathsOf(localSchema, `v2 ${definition.name}`);
+  const generated = sampleFor(definition.name, shippedSchema, false);
+  // У инструментов без строки карты нет canonicalArgs. Пустая база оставляет генератору
+  // отгруженной схемы возможность собрать обязательные поля и проверить такой случай.
+  const known = prepareKnownArgs(knownVariant.args ?? {}, shippedPaths, {
+    acceptV2: filterOf(definition, SAMPLE_WORKSPACE_ID),
+    mainRouteShape: routeShape(mainRequest),
+  });
+  const build = (knownArgs, sampled = generated) =>
+    buildShippedSample({
+      full: mergeShippedArgs(sampled, knownArgs),
+      known: knownArgs,
+      acceptShipped: filterOf(shippedDefinition, SAMPLE_WORKSPACE_ID),
+      acceptV2: filterOf(definition, SAMPLE_WORKSPACE_ID),
+      explains: (path, args) => schemaLagExplains(path, args, schemaLag, v2Paths),
+      shippedConstraints: shippedPaths,
+      goodValues: (path) =>
+        goodValuesOf(definition.name, knownVariant.variant, path, valuesAt(generated, path)[0]),
+      mainRouteShape: routeShape(mainRequest),
+    });
+  // У соседа десять поимённых запасных образцов для взаимоисключающих полей. Новый
+  // перебор обычно собирает их сам; оставляем запасной минимум и проверку протухания.
+  const fallback = SHIPPED_SAMPLE_FALLBACKS[key];
+  const candidates =
+    fallback === undefined
+      ? undefined
+      : shippedSampleCandidates(
+          key,
+          generated,
+          sampleFor(definition.name, shippedSchema, true),
+          knownVariant.args,
+        );
+  if (candidates !== undefined) {
+    usedShippedSampleFallbacks.add(key);
+    const fullShipped = filterOf(shippedDefinition, SAMPLE_WORKSPACE_ID)(candidates[0]);
+    const fullV2 = filterOf(definition, SAMPLE_WORKSPACE_ID)(candidates[0]);
+    if (fullShipped.ok && fullV2.ok && sameRoute(fullV2.request, mainRequest)) {
+      throw new Error(
+        `${key}: строка запасного образца протухла — полный отгруженный набор собирается`,
+      );
+    }
+  }
+  let outcome = build(known);
+  if (
+    outcome.impossible?.reason === 'SHIPPED_COMBINATION_LIMIT' ||
+    outcome.impossible?.reason === 'SHIPPED_REJECTS_EVERY_SET'
+  ) {
+    // Проверенное значение варианта могло быть переименовано (например, enum источника
+    // аудио), хотя поле и маршрут остались прежними. Берём только адресные отказы самого
+    // отгруженного фильтра и его же значение схемы; повтор должен пройти оба фильтра и
+    // сохранить маршрут, иначе это действительно вариант только v2.
+    const rejected = filterOf(shippedDefinition, SAMPLE_WORKSPACE_ID)(known);
+    const replaceable = (rejected.refusals ?? [])
+      .map((refusal) => refusal.path)
+      .filter(
+        (path) =>
+          path !== null && valuesAt(generated, path).length > 0 && valuesAt(known, path).length > 0,
+      );
+    if (replaceable.length > 0) {
+      const retry = build(withGeneratedValues(known, generated, replaceable));
+      if (retry.request !== undefined && sameRoute(retry.request, mainRequest)) outcome = retry;
+    }
+  }
+  if (outcome.impossible?.reason === 'SHIPPED_REJECTS_EVERY_SET' && candidates !== undefined) {
+    outcome = build(
+      prepareKnownArgs(candidates[1], shippedPaths),
+      sampleFor(definition.name, shippedSchema, true),
+    );
+  }
+  outcome = resolveShippedVariant({
+    outcome,
+    known,
+    generated,
+    schemaLag,
+    shippedConstraints: shippedPaths,
+    build,
+    mainRouteShape: routeShape(mainRequest),
+  });
+  if (outcome.request !== undefined && !sameRoute(outcome.request, mainRequest)) {
+    sampleFindings.push(
+      `${key}: образец отгруженного вызова ведёт в ${outcome.request.method ?? 'POST'} ${outcome.request.path.split('?')[0]}, ` +
+        `а вариант — в ${mainRequest.method ?? 'POST'} ${mainRequest.path.split('?')[0]}: сверка шла бы не тем входом`,
+    );
+  }
+  for (const refusal of outcome.refused) {
+    if (!observedRefusals.has(shippedName)) observedRefusals.set(shippedName, new Map());
+    observedRefusals
+      .get(shippedName)
+      .set(refusal.path, shippedPaths.get(refusal.path)?.type ?? 'any');
+  }
+  for (const message of outcome.pathless) {
+    sampleFindings.push(
+      `${key}: ветка v2 отвергла законный отгруженный вызов без пути — перенеси отказ в схему с путём (${message})`,
+    );
+  }
+  if (outcome.absentKnown.length > 0) {
+    sampleFindings.push(
+      `${key}: ветка v2 требует ${outcome.absentKnown.join(', ')}, а отгруженный клиент законно шлёт вызов без них`,
+    );
+  }
+  return outcome;
+}
+
+/** Годные значения пути: аргументы другого варианта или значение схемы, принятое его отгруженным фильтром. */
+function goodValuesOf(name, variant, path, generatedValue) {
+  const values = new Map();
+  const shippedName = shippedNameBySuccessor.get(name) ?? name;
+  const definition = shippedDefinitionByName.get(shippedName);
+  const schema = shippedSchemas.get(shippedName);
+  if (definition === undefined || schema === undefined) return [];
+  const accept = filterOf(definition, SAMPLE_WORKSPACE_ID);
+  const paths = schemaPathsOf(schema, `отгруженный ${shippedName}`);
+  for (const other of variantsByTool.get(name) ?? []) {
+    if (other.variant === variant || other.args === undefined) continue;
+    const candidate = prepareKnownArgs(other.args, paths);
+    // Значение «заведомо годное» лишь тогда, когда другой вариант отгруженный фильтр
+    // действительно ПРИНЯЛ. Совпадение с JSON-схемой не доказывает refine Zod.
+    if (!accept(candidate).ok) continue;
+    for (const value of valuesAt(candidate, path)) values.set(JSON.stringify(value), value);
+    // В карте другого варианта поле могло отсутствовать: manager_id у meta запрещён, а
+    // summary/cohorts принимают число из отгруженной схемы. Проверяем это ИСПОЛНЯЕМЫМ
+    // отгруженным фильтром, прежде чем считать значение годным для альтернативы.
+    if (generatedValue !== undefined && valuesAt(candidate, path).length === 0) {
+      const enriched = withValueAt(candidate, path, generatedValue);
+      if (accept(enriched).ok) values.set(JSON.stringify(generatedValue), generatedValue);
+    }
+  }
+  return [...values.values()];
+}
+
+const staleShippedSampleFallbacks = Object.keys(SHIPPED_SAMPLE_FALLBACKS).filter(
+  (key) => !usedShippedSampleFallbacks.has(key),
+);
+if (staleShippedSampleFallbacks.length > 0) {
+  throw new Error(
+    `Запасной образец больше не имеет отгруженного маршрута: ${staleShippedSampleFallbacks.join(', ')}`,
+  );
+}
+
+if (failed.length > 0) {
+  console.error(`Не удалось вывести маршрут для: ${failed.join(', ')}`);
+  process.exit(1);
+}
+
+// Наблюдённый отказ ветки v2 на законном отгруженном вызове — такое же расхождение контракта, как найденное
+// сравнением схем, только живущее в коде инструмента: строка `инструмент::путь#refused`. Сверка — по объединению.
+const refusalLag = [...observedRefusals].flatMap(([tool, paths]) =>
+  [...paths].map(([path, shippedType]) => ({
+    tool,
+    path: `${path}#refused`,
+    kind: 'REFUSED',
+    shipped: shippedType,
+    v2: 'refused',
+  })),
+);
+const foundLag = [...diff.contractLag, ...refusalLag].sort((a, b) =>
+  a.tool === b.tool ? a.path.localeCompare(b.path) : a.tool.localeCompare(b.tool),
+);
+const reconciliation = reconcileWithRegistry({ ...diff, contractLag: foundLag }, lagRegistry);
+const problems = [];
+problems.push(...variantExtensionFindings({
+  tools,
+  extensions: lagRegistry.contractExtensions ?? {},
+  shippedSchemas,
+  localSchemas,
+  variantsByTool,
+}));
+if (sampleFindings.length > 0) {
+  problems.push(`Образцы отгруженных вызовов:\n  ${sampleFindings.join('\n  ')}`);
+}
+if (reconciliation.undeclaredMissing.length > 0) {
+  problems.push(
+    `Отгруженные инструменты, которых нет в ветке v2 и нет в реестре отставания:\n  ${reconciliation.undeclaredMissing.join('\n  ')}`,
+  );
+}
+if (reconciliation.undeclaredLag.length > 0) {
+  problems.push(
+    `Расхождения контракта, не объявленные в реестре отставания:\n  ${reconciliation.undeclaredLag.join('\n  ')}`,
+  );
+}
+if (reconciliation.incomplete.length > 0) {
+  problems.push(
+    `Строки реестра без причины, владельца или тяжести из словаря:\n  ${reconciliation.incomplete.join('\n  ')}`,
+  );
+}
+if (reconciliation.staleMissing.length > 0 || reconciliation.staleLag.length > 0) {
+  problems.push(
+    'Протухшие строки реестра отставания (расхождения больше нет — строку надо снять):\n  ' +
+      [...reconciliation.staleMissing, ...reconciliation.staleLag].join('\n  '),
+  );
+}
+if (problems.length > 0) {
+  console.error(problems.join('\n\n'));
+  process.exit(1);
+}
+
+// Fail-closed: записей ровно столько, сколько пар «инструмент × ветка» задаёт фикстура.
+//
+// ⛔ Ожидаемое число считается ПО САМОЙ ФИКСТУРЕ (`variantsByTool`), а не повторным вызовом
+// `variantsOf` — иначе проверка была бы тавтологией цикла выгрузки. Ловит именно тот класс, который
+// назвал Гейт A: подмена «безфикстурный инструмент даёт один безымянный вариант» на «даёт пустой
+// список» молча выкинула бы из артефакта 26 инструментов (ICP, песочница, промпт-операции, каталог
+// моделей, оба инструмента аналитики), и ни один тест на стороне API этого не увидел бы — их там
+// нет и сравнивать не с чем.
+const expectedRecordCount = toolDefinitions.reduce(
+  (sum, definition) =>
+    sum +
+    (typeof definition.createRequest !== 'function'
+      ? 1
+      : Math.max(1, variantsByTool.get(definition.name)?.length ?? 0)),
+  0,
+);
+if (tools.length !== expectedRecordCount) {
+  console.error(
+    `Записей в выгрузке ${tools.length}, а пар «инструмент × ветка» ${expectedRecordCount}: ` +
+      'вариант потерян на выгрузке.',
+  );
+  process.exit(1);
+}
+
+// Схемы входа обоих реестров — для сверки аргументов, которые называет навигация рабочей области (см. модуль схем).
+// Выгружаемый инструмент без схемы ветки v2 — отказ сразу, для всех инструментов, а не красный сторож позже на сервере.
+const shippedInputSchemas = collectInputSchemas(shipped.tools, 'отгруженный реестр');
+const v2InputSchemas = collectInputSchemas(localRegistry.tools, 'ветка v2');
+const withoutV2Schema = namesWithoutSchema(
+  tools.map((tool) => tool.name),
+  v2InputSchemas,
+);
+if (withoutV2Schema.length > 0) {
+  console.error(
+    `Нет схемы входа ветки v2 у выгружаемых инструментов: ${withoutV2Schema.join(', ')}`,
+  );
+  process.exit(1);
+}
+
+// Отставание уезжает ОТДЕЛЬНЫМИ ключами, а не третьим видом записи внутри `tools`: `tools` —
+// реестр реально существующих в v2 инструментов, и расширение его множества ослабило бы проверку
+// «каждая запись серверной карты существует в пакете».
+const payload = {
+  $comment:
+    'СГЕНЕРИРОВАНО besales-mcp (yarn publish:mcp-registry). Руками не править: правка потеряется при следующей выгрузке. ' +
+    'Запись = пара «инструмент × ветка»: у ветвящегося инструмента (вход решает метод или форму адреса) записей столько, сколько веток, и они различаются полем variant; ' +
+    'у неветвящегося поле variant отсутствует, а запись одна. Поэтому число записей БОЛЬШЕ числа инструментов. ' +
+    'samplePath — конкретный путь прогона, сопоставляется с шаблонами Nest посегментно. ' +
+    'shippedInputSchemas и v2InputSchemas — схемы входа всех инструментов отгруженного реестра и ветки v2 по имени (сверка аргументов навигации рабочей области).',
+  shippedRegistry: shipped.provenance,
+  // ⛔ Не справка, а ВХОД чужой проверки: besales-api по этому списку решает, менялось ли на
+  // отгружаемой линии то, из чего собрана выгрузка. Список берётся у самих чтений (загрузчик +
+  // исходник клиента), а не пишется здесь третьей копией.
+  // Замыкание импортов отгруженных определений — тоже вход: выгрузка ИСПОЛНЯЕТ отгруженный фильтр.
+  shippedInputPaths: [
+    ...new Set([...SHIPPED_INPUT_PATHS, SHIPPED_CLIENT_SOURCE, ...shippedDefinitions.inputPaths]),
+  ].sort(),
+  generatorV2Commit,
+  connectScopes,
+  v2ConnectScopes,
+  tools,
+  shippedOnly: diff.missingTools.map((name) => ({
+    name,
+    ...lagRegistry.missingTools[name],
+  })),
+  contractLag: foundLag.map((entry) => ({
+    ...entry,
+    ...lagRegistry.contractLag[lagKey(entry)],
+  })),
+  // ⛔ Связь «прежнее имя → имя в v2» уезжает в выгрузку, потому что без неё besales-api не
+  // отличает переименованный инструмент от пропавшего: у переименованного отгруженное имя
+  // ИСЧЕЗАЕТ с поверхности, и клиент, зовущий его сегодня, получит «инструмент не найден».
+  // Эта пара — единственное, чем такой разрыв виден отдельно от расхождений полей.
+  toolSuccessors: lagRegistry.toolSuccessors ?? {},
+  // Все разделы долга доезжают до независимого потребителя API.
+  ...remainingLagSections(lagRegistry),
+  shippedInputSchemas,
+  v2InputSchemas,
+};
+
+writeFileSync(OUT, `${JSON.stringify(payload, null, 2)}\n`);
+// ⛔ Записи и инструменты — РАЗНЫЕ величины с тех пор, как ветвящийся инструмент даёт запись на
+// ветку. Прежняя строка называла записи инструментами и разошлась бы с реальностью ровно там, где
+// человек сверяет её глазами с числом инструментов реестра.
+const apiRecords = tools.filter((t) => t.kind === 'api');
+const distinctToolCount = new Set(tools.map((t) => t.name)).size;
+const branchingToolCount = new Set(
+  apiRecords.filter((t) => t.variant !== undefined).map((t) => t.name),
+).size;
+console.log(
+  `Выгружено записей: ${tools.length} (api: ${apiRecords.length}) у ${distinctToolCount} инструментов, ` +
+    `из них ветвящихся: ${branchingToolCount}; ` +
+    `эталон ${shipped.provenance.source}:${shipped.provenance.ref ?? shipped.provenance.path}@${String(shipped.provenance.commit).slice(0, 7)} ` +
+    `(${shipped.provenance.toolCount} инструментов); отгружено-без-v2: ${diff.missingTools.length}; расхождений контракта: ${foundLag.length} ` +
+    `(из них отказов в коде инструмента: ${refusalLag.length}); образцов с альтернативами: ${tools.filter((t) => t.shippedSampleAlternatives).length}, ` +
+    `невозможных: ${tools.filter((t) => t.shippedSampleImpossible).length}; ` +
+    `схем входа: отгружено ${Object.keys(shippedInputSchemas).length}, ветка v2 ${Object.keys(v2InputSchemas).length}`,
+);