@besales/mcp 0.48.0 → 1.0.0-beta.2

package/scripts/shipped-sample.mjs

@@ -0,0 +1,868 @@
+// Образец ОТГРУЖЕННОГО вызова и ответ ветки v2 на него.
+//
+// ⭐ Сверка «примет ли v2 то, что шлёт отгруженный клиент» честна, только если образец — ЗАКОННЫЙ вызов отгруженного
+// клиента. Полный набор полей его схемы им часто не является: поля бывают взаимоисключающими, и такой набор отвергает
+// сам отгруженный инструмент. Поэтому образец обязан пройти отгруженный ФИЛЬТР (схему zod и конструктор запроса), а
+// уже потом — фильтр ветки v2.
+//
+// ⛔ Отвергнутые формы решения: «снимать поля, пока v2 не примет» прятала бы настоящие отказы v2 — снятие делает образец
+// зелёным ровно там, где клиенту откажут; рукописный реестр взаимоисключений — вторая копия правил, которая протухнет и
+// не видит случаев, где v2 строже отгруженного.
+//
+// Модуль — чистые функции: фильтры и реестры приходят параметрами, выгрузка их собирает.
+import { schemaConstraints } from './registry-diff.mjs';
+
+/** Закрытый перечень причин «образец невозможен» уровня случая. */
+export const SHIPPED_SAMPLE_IMPOSSIBLE_REASONS = Object.freeze([
+  'SHIPPED_REJECTS_EVERY_SET',
+  'V2_REQUIRES_FIELD_UNKNOWN_TO_SHIPPED',
+  'SHIPPED_DEFINITION_UNAVAILABLE',
+  // Проверенное значение, задающее вариант, отгруженная схема не принимает (объявлено строкой ограничения): такой
+  // формы у отгруженного клиента нет, сверять нечего. Сервер объясняет её строкой ограничения, а не строкой реестра.
+  'V2_ONLY_VARIANT',
+  'SHIPPED_COMBINATION_LIMIT',
+]);
+
+/**
+ * Почему путь снят с образца: `DECLARED` — ветка v2 отвергает его, и отказ объявлен реестром отставания;
+ * `SHIPPED_FORBIDS` — отгруженный инструмент не принимает поле в этой форме варианта даже с заведомо годным значением;
+ * `VALUE_NOT_FOUND` — годного значения подобрать не из чего (видимая причина, сервер требует строку реестра);
+ * `SHIPPED_REJECTS_KNOWN` — проверенное значение варианта отгруженный фильтр не принимает, и законный вызов того же
+ * маршрута собран без него (форма ветки v2, которую отгруженный клиент не пошлёт).
+ */
+export const SHIPPED_SAMPLE_OMISSIONS = Object.freeze([
+  'DECLARED',
+  'SHIPPED_FORBIDS',
+  'VALUE_NOT_FOUND',
+  'SHIPPED_REJECTS_KNOWN',
+  'SEARCH_LIMIT_EXCEEDED',
+]);
+
+/** Предел перебора подмножеств снимаемых путей. */
+export const SUBSET_LIMIT = 3;
+const ALTERNATIVE_CANDIDATE_LIMIT = 512;
+const MAX_ROUNDS = 12;
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** Путь проблемы zod в нотации реестра отставания: индексы массива — `[]`. */
+export function normalizeIssuePath(segments) {
+  let out = '';
+  for (const segment of segments ?? []) {
+    if (typeof segment === 'number') out += '[]';
+    else out += out === '' ? String(segment) : `.${String(segment)}`;
+  }
+  return out;
+}
+
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Пути отказа фильтра; `path: null` — отказ без пути (правило корня, исключение конструктора запроса). */
+export function refusalPaths(error) {
+  if (!Array.isArray(error?.issues)) return [{ path: null, message: messageOf(error) }];
+  const out = [];
+  const visit = (issue, prefix = []) => {
+    const segments = [...prefix, ...(issue.path ?? [])];
+    // Zod 4: `errors` — массив веток; Zod 3: `unionErrors` — массив ZodError.
+    const branches = issue.code === 'invalid_union'
+      ? issue.errors ?? issue.unionErrors?.map((branch) => branch.issues)
+      : undefined;
+    if (Array.isArray(branches)) {
+      for (const branch of branches) {
+        for (const nested of branch) visit(nested, segments);
+      }
+      return;
+    }
+    const base = normalizeIssuePath(segments);
+    if (issue.code === 'unrecognized_keys' && Array.isArray(issue.keys)) {
+      for (const key of issue.keys) out.push({ path: base === '' ? key : `${base}.${key}`, message: issue.message });
+      return;
+    }
+    out.push({ path: base === '' ? null : base, message: issue.message });
+  };
+  for (const issue of error.issues) visit(issue);
+  return out;
+}
+
+/** Фильтр определения: разбор схемой, подстановка рабочей области по умолчанию, конструктор запроса. */
+export function filterOf(definition, workspaceId) {
+  return (args) => {
+    try {
+      let input = definition.schema.parse(args);
+      if (definition.defaultWorkspaceId && input.workspace_id === undefined) {
+        input = definition.schema.parse({ ...input, workspace_id: workspaceId });
+      }
+      return { ok: true, request: definition.createRequest(input) };
+    } catch (error) {
+      return { ok: false, refusals: refusalPaths(error) };
+    }
+  };
+}
+
+/** `a[].b` → `['a', '[]', 'b']`. */
+export function splitPath(path) {
+  const out = [];
+  for (const part of path.split('.')) {
+    const match = /^(.*?)((?:\[\])*)$/u.exec(part);
+    if (match[1] !== '') out.push(match[1]);
+    for (let index = 0; index < match[2].length / 2; index += 1) out.push('[]');
+  }
+  return out;
+}
+
+/** Значения по пути; массив раскрывается по всем элементам. */
+export function valuesAt(value, path) {
+  let current = [value];
+  for (const segment of splitPath(path)) {
+    const next = [];
+    for (const node of current) {
+      if (segment === '[]') {
+        if (Array.isArray(node)) next.push(...node);
+      } else if (isObject(node) && Object.hasOwn(node, segment)) {
+        next.push(node[segment]);
+      }
+    }
+    current = next;
+  }
+  return current;
+}
+
+export function hasPath(value, path) {
+  return valuesAt(value, path).length > 0;
+}
+
+function rewriteAt(value, path, leaf) {
+  const segments = splitPath(path);
+  const visit = (node, index) => {
+    const segment = segments[index];
+    const last = index === segments.length - 1;
+    if (segment === '[]') {
+      if (!Array.isArray(node)) return node;
+      return last ? leaf(node, undefined) : node.map((item) => visit(item, index + 1));
+    }
+    if (!isObject(node)) return node;
+    if (last) return leaf(node, segment);
+    if (!Object.hasOwn(node, segment)) return node;
+    const child = visit(node[segment], index + 1);
+    const out = { ...node };
+    if (child === undefined) delete out[segment];
+    else out[segment] = child;
+    return out;
+  };
+  return visit(value, 0);
+}
+
+/** Копия без пути; путь внутри массива снимается у каждого элемента, путь `x[]` снимает сам массив. */
+export function withoutPath(value, path) {
+  return rewriteAt(value, path, (node, key) => {
+    if (key === undefined) return undefined;
+    if (!Object.hasOwn(node, key)) return node;
+    const out = { ...node };
+    delete out[key];
+    return out;
+  });
+}
+
+/** Копия с заданным значением по пути (у каждого элемента массива на пути). */
+export function withValueAt(value, path, leafValue) {
+  return rewriteAt(value, path, (node, key) => (key === undefined ? node : { ...node, [key]: leafValue }));
+}
+
+/** Единица покрывает путь отказа, если она и есть этот путь или его предок. */
+export function coversPath(unit, path) {
+  return path === unit || path.startsWith(`${unit}.`) || path.startsWith(`${unit}[]`);
+}
+
+/** Пути связаны, если один — предок другого или они равны. */
+export function relatedPaths(a, b) {
+  return a === b || b.startsWith(`${a}.`) || b.startsWith(`${a}[]`) || a.startsWith(`${b}.`) || a.startsWith(`${b}[]`);
+}
+
+/**
+ * Корни путей, которые генератор добавил поверх проверенных аргументов: самый короткий путь, которого нет у проверенных,
+ * при том что его родитель у них есть. Снимается корень целиком — снятие одних листьев оставляло бы пустые элементы
+ * массива, которые фильтр читает как заданное поле. Порядок — порядок полей схемы.
+ */
+export function generatedRoots(full, known, prefix = '') {
+  const roots = [];
+  if (isObject(full)) {
+    for (const [key, value] of Object.entries(full)) {
+      const path = prefix === '' ? key : `${prefix}.${key}`;
+      if (!isObject(known) || !Object.hasOwn(known, key)) roots.push(path);
+      else roots.push(...generatedRoots(value, known[key], path));
+    }
+  } else if (Array.isArray(full) && Array.isArray(known) && full.length > 0 && known.length > 0) {
+    roots.push(...generatedRoots(full[0], known[0], `${prefix}[]`));
+  }
+  return roots;
+}
+
+/** Снимаемые единицы проверенных аргументов для поиска альтернатив: поля верхнего уровня и листья вложенных. */
+export function knownUnits(known) {
+  if (!isObject(known)) return [];
+  const units = [];
+  const leaves = (value, prefix) => {
+    if (isObject(value) && Object.keys(value).length > 0) {
+      return Object.entries(value).flatMap(([key, child]) => leaves(child, `${prefix}.${key}`));
+    }
+    if (Array.isArray(value) && value.length > 0 && isObject(value[0])) return leaves(value[0], `${prefix}[]`);
+    return [prefix];
+  };
+  for (const [key, value] of Object.entries(known)) {
+    units.push(key);
+    if (isObject(value) || (Array.isArray(value) && isObject(value[0]))) {
+      units.push(...leaves(value, key).filter((path) => path !== key));
+    }
+  }
+  return units;
+}
+
+/** Листья сгенерированного корня: корень остаётся, а ошибочный вложенный ключ можно снять. */
+function leavesUnder(value, path) {
+  const [root] = valuesAt(value, path);
+  if (!isObject(root)) return [];
+  const walk = (node, prefix) => {
+    if (isObject(node)) {
+      return Object.entries(node).flatMap(([key, child]) => walk(child, `${prefix}.${key}`));
+    }
+    if (Array.isArray(node) && isObject(node[0])) return walk(node[0], `${prefix}[]`);
+    return [prefix];
+  };
+  return walk(root, path);
+}
+
+/** Подмножества по возрастанию размера до `maxSize`, внутри размера — в порядке списка. */
+export function* subsetsUpTo(items, maxSize) {
+  for (let size = 1; size <= Math.min(maxSize, items.length); size += 1) {
+    const index = Array.from({ length: size }, (_, position) => position);
+    for (;;) {
+      yield index.map((position) => items[position]);
+      let cursor = size - 1;
+      while (cursor >= 0 && index[cursor] === items.length - size + cursor) cursor -= 1;
+      if (cursor < 0) break;
+      index[cursor] += 1;
+      for (let next = cursor + 1; next < size; next += 1) index[next] = index[next - 1] + 1;
+    }
+  }
+}
+
+/** Пустая добавка и затем ограниченные группы, без создания полного списка сочетаний в памяти. */
+function* additionsUpTo(items, maxSize) {
+  yield [];
+  yield* subsetsUpTo(items, maxSize);
+}
+
+/**
+ * Законный вызов снятием единиц `removable`; `keep` и связанные с ним единицы не трогаются. Сначала снимаются единицы,
+ * которые называют пути отказа; отказ без пути — перебор подмножеств по возрастанию размера до {@link SUBSET_LIMIT}.
+ *
+ * @returns {{ args: unknown, removed: string[], verdict: { ok: true } } | null}
+ */
+export function findLegalCall(start, removable, accept, keep = []) {
+  let current = start;
+  const removed = [];
+  for (let round = 0; round < MAX_ROUNDS; round += 1) {
+    const verdict = accept(current);
+    if (verdict.ok) return { args: current, removed, verdict };
+    const present = removable.filter(
+      (unit) =>
+        !removed.includes(unit) && hasPath(current, unit) && !keep.some((kept) => coversPath(unit, kept)),
+    );
+    // Снимается только поле отказа или его предок: отказ правила ОБЪЕКТА (путь — сам объект) не называет, какое из
+    // вложенных полей лишнее, и снятие всех разом ломало бы вызов; такой отказ решает перебор.
+    const guided = present.filter((unit) =>
+      verdict.refusals.some((refusal) => refusal.path !== null && coversPath(unit, refusal.path)),
+    );
+    if (guided.length > 0) {
+      for (const unit of guided) current = withoutPath(current, unit);
+      removed.push(...guided);
+      continue;
+    }
+    for (const subset of subsetsUpTo(present, SUBSET_LIMIT)) {
+      const candidate = subset.reduce((args, unit) => withoutPath(args, unit), current);
+      const attempt = accept(candidate);
+      if (attempt.ok) return { args: candidate, removed: [...removed, ...subset], verdict: attempt };
+    }
+    return present.length > SUBSET_LIMIT
+      ? { limitExceeded: present, args: current, removed, verdict }
+      : null;
+  }
+  return null;
+}
+
+/** Форма маршрута: метод и адрес без строки запроса, идентификаторы — заполнителем. */
+export function routeShape(request) {
+  const path = request.path
+    .split('?')[0]
+    .split('/')
+    .map((segment) => (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(segment) || /^\d+$/u.test(segment) ? ':id' : segment))
+    .join('/');
+  return `${request.method ?? 'POST'} ${path}`;
+}
+
+/**
+ * Законный вызов НАРАЩИВАНИЕМ: от базы (проверенные аргументы) единицы `units` добавляются по одной в порядке списка;
+ * единица остаётся, если фильтр принимает набор и маршрут отгруженного вызова не меняется (поле, переключающее
+ * маршрут — идентификатор правки вместо создания, — задаёт ДРУГОЙ вариант). Перебор подмножеств тут не нужен:
+ * отчёт, чей фильтр запрещает десяток параметров разом, собирается за один проход.
+ *
+ * @returns {{ args: unknown, removed: string[], verdict: { ok: true } } | null} `null` — база сама незаконна
+ */
+export function growLegalCall(base, source, units, accept) {
+  const baseVerdict = accept(base);
+  if (!baseVerdict.ok) return null;
+  const shape = routeShape(baseVerdict.request);
+  const fullVerdict = accept(source);
+  if (fullVerdict.ok && routeShape(fullVerdict.request) === shape) {
+    return { args: source, removed: [], verdict: fullVerdict };
+  }
+  let current = base;
+  let verdict = baseVerdict;
+  const removed = [];
+  for (const unit of units) {
+    const [value] = valuesAt(source, unit);
+    const candidate = value === undefined ? current : withValueAt(current, unit, value);
+    const attempt = accept(candidate);
+    if (attempt.ok && routeShape(attempt.request) === shape) {
+      current = candidate;
+      verdict = attempt;
+    } else {
+      removed.push(unit);
+    }
+  }
+  // Некоторые необязательные поля законны лишь ВМЕСТЕ. Добавляем принятые группы до
+  // неподвижной точки. Остаток разбирается поимённо поиском альтернатив с явным пределом.
+  let pending = removed;
+  for (;;) {
+    let accepted = null;
+    for (const subset of subsetsUpTo(pending, SUBSET_LIMIT)) {
+      const candidate = subset.reduce((args, unit) => {
+        const [value] = valuesAt(source, unit);
+        return value === undefined ? args : withValueAt(args, unit, value);
+      }, current);
+      const attempt = accept(candidate);
+      if (attempt.ok && routeShape(attempt.request) === shape) accepted = { subset, candidate, attempt };
+    }
+    if (accepted === null) break;
+    current = accepted.candidate;
+    verdict = accepted.attempt;
+    pending = pending.filter((unit) => !accepted.subset.includes(unit));
+  }
+  return { args: current, removed: pending, verdict };
+}
+
+const FORMAT_CHECKS = {
+  uuid: (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value),
+  date: (value) => /^\d{4}-\d{2}-\d{2}$/u.test(value),
+  'date-time': (value) => !Number.isNaN(Date.parse(value)) && /T/u.test(value),
+  email: (value) => /^[^@\s]+@[^@\s]+$/u.test(value),
+  uri: (value) => {
+    try {
+      return Boolean(new URL(value));
+    } catch {
+      return false;
+    }
+  },
+};
+
+/** Нарушает ли значение ограничение `kind` узла схемы ветки v2. */
+export function violatesConstraint(kind, constraints, value) {
+  if (constraints === undefined) return false;
+  switch (kind) {
+    case 'enum':
+      return constraints.enum !== undefined && !constraints.enum.split('|').includes(String(value));
+    case 'pattern':
+      try {
+        return typeof value === 'string' && !new RegExp(constraints.pattern, 'u').test(value);
+      } catch {
+        return false;
+      }
+    case 'format':
+      return typeof value === 'string' && FORMAT_CHECKS[constraints.format]?.(value) === false;
+    case 'minimum':
+      return typeof value === 'number' && value < constraints.minimum;
+    case 'maximum':
+      return typeof value === 'number' && value > constraints.maximum;
+    case 'minLength':
+      return typeof value === 'string' && value.length < constraints.minLength;
+    case 'maxLength':
+      return typeof value === 'string' && value.length > constraints.maxLength;
+    case 'minItems':
+      return Array.isArray(value) && value.length < constraints.minItems;
+    case 'maxItems':
+      return Array.isArray(value) && value.length > constraints.maxItems;
+    case 'type': {
+      const declared = Array.isArray(constraints.type) ? constraints.type : [constraints.type];
+      const actual = Array.isArray(value) ? 'array' : value === null ? 'null' : typeof value;
+      const matches = declared.some(
+        (type) => type === actual || (type === 'integer' && Number.isInteger(value)) || type === undefined,
+      );
+      return !matches;
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * Объясняет ли СРАВНЕНИЕ СХЕМ отказ v2 по пути: поля нет в v2, либо ограничение на этом пути отличается и значение
+ * образца его действительно нарушает. Строка ограничения, которое значение не нарушает, отказ не объясняет — иначе
+ * строка «объясняла» бы чужой класс отказа.
+ *
+ * @param {ReadonlyArray<{ path: string, kind: string }>} schemaLag строки сравнения схем этого инструмента
+ */
+export function schemaLagExplains(path, args, schemaLag, v2Constraints) {
+  for (const row of schemaLag) {
+    const [rowPath, kind] = row.path.split('#');
+    if (row.kind === 'MISSING_FIELD' && relatedPaths(rowPath, path)) return true;
+    if (row.kind === 'CONSTRAINT' && rowPath === path && kind !== 'required') {
+      if (valuesAt(args, path).some((value) => violatesConstraint(kind, v2Constraints.get(path), value))) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Ответ ветки v2 на законный отгруженный вызов.
+ *
+ * Отказ, который объясняет сравнение схем, снимает путь (`DECLARED`). Прочий отказ по пути — наблюдённый отказ,
+ * живущий в коде инструмента: путь снимается, а отказ уходит в сверку с реестром (там он обязан быть объявлен строкой
+ * `#refused`). Отказ без пути — находка другого рода: отказ обязан жить в схеме с путём. Путь, которого нет в образце,
+ * — поле, которое v2 требует, а образец не несёт.
+ */
+export function v2Verdict(args, acceptV2, explains) {
+  let current = args;
+  const omitted = [];
+  const refused = [];
+  for (let round = 0; round < MAX_ROUNDS; round += 1) {
+    const verdict = acceptV2(current);
+    if (verdict.ok) return { request: verdict.request, args: current, omitted, refused };
+    const pathless = verdict.refusals.filter((refusal) => refusal.path === null);
+    if (pathless.length > 0) return { pathless: pathless.map((refusal) => refusal.message), omitted, refused };
+    const absent = [...new Set(verdict.refusals.filter((r) => !hasPath(current, r.path)).map((r) => r.path))];
+    if (absent.length > 0) return { absent, omitted, refused };
+    for (const path of [...new Set(verdict.refusals.map((refusal) => refusal.path))]) {
+      if (!explains(path, current)) {
+        refused.push({
+          path,
+          message: verdict.refusals.find((refusal) => refusal.path === path)?.message ?? '',
+        });
+      }
+      current = withoutPath(current, path);
+      omitted.push({ path, why: 'DECLARED' });
+    }
+  }
+  return { pathless: ['ветка v2 не приняла образец за предел раундов снятия'], omitted, refused };
+}
+
+/**
+ * Образец отгруженного вызова для пары «инструмент × вариант».
+ *
+ * @param {object} input
+ * @param {unknown} input.full набор: образец отгруженной схемы поверх проверенных аргументов (шаг 0 уже применён)
+ * @param {unknown} input.known проверенные аргументы варианта
+ * @param {(args: unknown) => object} input.acceptShipped отгруженный фильтр
+ * @param {(args: unknown) => object} input.acceptV2 фильтр ветки v2
+ * @param {(path: string, args: unknown) => boolean} input.explains объясняет ли сравнение схем отказ v2 по пути
+ * @param {Map<string, object>} input.shippedConstraints пути отгруженной схемы с ограничениями (`schemaPathsOf`)
+ * @param {(path: string) => unknown[]} input.goodValues заведомо годные значения пути (проверенные аргументы других
+ *   вариантов того же инструмента)
+ * @param {string} [input.mainRouteShape] форма маршрута варианта (`routeShape` его запроса ветки v2)
+ */
+export function buildShippedSample(input) {
+  const { full, known, acceptShipped, acceptV2, explains, shippedConstraints, goodValues, mainRouteShape } = input;
+  const shippedKnows = (path) => shippedConstraints.has(path);
+  const result = { omitted: [], alternatives: [], refused: [], pathless: [], absentKnown: [] };
+  const roots = generatedRoots(full, known);
+  const base = roots.reduce((args, unit) => withoutPath(args, unit), full);
+  // База законна — наращивание (не зависит от числа конфликтов); незаконна (отгруженный требует поле, которого нет у
+  // проверенных) — снятие по путям отказа и перебор от полного набора.
+  let legal = growLegalCall(base, full, roots, acceptShipped) ?? findLegalCall(full, roots, acceptShipped);
+  // Полный набор может требовать снять десятки необязательных полей, хотя база незаконна всего
+  // из-за одного-двух проверенных полей v2. Прежде ранний выход скрывал эту короткую правку.
+  const initialLimit = legal?.limitExceeded;
+  if (initialLimit) legal = null;
+  let knownRemoved = [];
+  let movedVariant = [];
+  if (legal === null) {
+    // Сами проверенные аргументы отгруженный фильтр не принимает (форма ветки v2: параметр, запрещённый отгруженным
+    // для этого варианта, или значение другой формы). Снимается наименьшее число проверенных полей — перебором, без
+    // снятия по пути отказа: путь отказа здесь часто указывает на поле, ЗАДАЮЩЕЕ вариант, — и маршрут ветки v2
+    // обязан остаться маршрутом варианта.
+    const acceptSameRoute = (args) => {
+      const shipped = acceptShipped(args);
+      if (!shipped.ok) return shipped;
+      const v2 = v2Verdict(args, acceptV2, explains);
+      const same = v2.request !== undefined && (mainRouteShape === undefined || routeShape(v2.request) === mainRouteShape);
+      return same ? shipped : { ok: false, refusals: [{ path: null, message: 'другой маршрут' }] };
+    };
+    for (const subset of subsetsUpTo(knownUnits(known), SUBSET_LIMIT)) {
+      const reduced = subset.reduce((args, unit) => withoutPath(args, unit), base);
+      if (!acceptSameRoute(reduced).ok) {
+        const shipped = acceptShipped(reduced);
+        const v2 = shipped.ok ? v2Verdict(reduced, acceptV2, explains) : null;
+        if (v2?.request !== undefined && mainRouteShape !== undefined &&
+            routeShape(v2.request) !== mainRouteShape && movedVariant.length === 0) movedVariant = subset;
+        continue;
+      }
+      legal = growLegalCall(reduced, full, roots, acceptShipped);
+      if (legal?.limitExceeded) {
+        result.impossible = { reason: 'SHIPPED_COMBINATION_LIMIT', paths: legal.limitExceeded,
+          message: `Проверить нельзя: законная комбинация может требовать более ${SUBSET_LIMIT} полей` };
+        return result;
+      }
+      knownRemoved = subset;
+      break;
+    }
+  }
+  if (legal === null) {
+    if (movedVariant.length > 0) {
+      result.impossible = { reason: 'V2_ONLY_VARIANT', paths: movedVariant };
+      return result;
+    }
+    if (initialLimit) {
+      result.impossible = { reason: 'SHIPPED_COMBINATION_LIMIT', paths: initialLimit,
+        message: `Проверить нельзя: законная комбинация может требовать более ${SUBSET_LIMIT} полей` };
+      return result;
+    }
+    const refusals = acceptShipped(full).refusals ?? [];
+    result.impossible = {
+      reason: 'SHIPPED_REJECTS_EVERY_SET',
+      paths: [...new Set(refusals.map((refusal) => refusal.path ?? '(корень)'))].sort(),
+    };
+    return result;
+  }
+  let main = v2Verdict(legal.args, acceptV2, explains);
+  if (main.absent) {
+    const unknown = main.absent.filter((path) => !shippedKnows(path));
+    if (unknown.length > 0) {
+      result.impossible = { reason: 'V2_REQUIRES_FIELD_UNKNOWN_TO_SHIPPED', paths: unknown.sort() };
+      return result;
+    }
+    // Поле, которое v2 требует, отгруженный знает, но первый законный набор его снял (конфликт с соседним полем):
+    // ищется законный набор, который это поле СОХРАНЯЕТ. Не нашёлся — отгруженный клиент законно шлёт вызов без
+    // поля, которое v2 требует: находка.
+    const keeping = findLegalCall(full, roots, acceptShipped, main.absent);
+    if (keeping?.limitExceeded) {
+      result.impossible = { reason: 'SHIPPED_COMBINATION_LIMIT', paths: keeping.limitExceeded,
+        message: `Проверить нельзя: сохранение обязательного поля требует перебора более ${SUBSET_LIMIT} полей` };
+      return result;
+    }
+    const retried = keeping === null ? null : v2Verdict(keeping.args, acceptV2, explains);
+    if (keeping === null || retried.absent) {
+      result.refused.push(...main.refused);
+      result.absentKnown.push(...main.absent);
+      return result;
+    }
+    legal = keeping;
+    main = retried;
+  }
+  if (main.pathless) {
+    result.refused.push(...main.refused);
+    result.pathless.push(...main.pathless);
+    return result;
+  }
+  result.request = main.request;
+  result.originalRequest = acceptShipped(legal.args).request;
+  result.omitted.push(...knownRemoved.map((path) => ({ path, why: 'SHIPPED_REJECTS_KNOWN' })));
+  result.omitted.push(...main.omitted);
+  result.refused.push(...main.refused);
+
+  // Шаг 3: для каждого снятого на шаге 1 пути — законный вызов, который его СОДЕРЖИТ.
+  const removable = [...generatedRoots(full, known), ...knownUnits(known)];
+  const acceptAlternative = (args) => {
+    const shipped = acceptShipped(args);
+    return shipped;
+  };
+  for (const path of legal.removed) {
+    const found = findAlternative(full, legal.args, path, removable, acceptAlternative, {
+      values: goodValues(path),
+      shippedConstraints,
+    });
+    if (found.kind === 'FOUND') {
+      const v2 = v2Verdict(found.args, acceptV2, explains);
+      if (v2.absent) {
+        result.absentKnown.push(...v2.absent);
+        continue;
+      }
+      if (v2.pathless) {
+        result.pathless.push(...v2.pathless);
+        continue;
+      }
+      result.refused.push(...v2.refused);
+      result.alternatives.push({ forPath: path, request: v2.request, omitted: v2.omitted });
+      continue;
+    }
+    result.omitted.push({ path, why: found.kind,
+      ...(found.kind === 'SEARCH_LIMIT_EXCEEDED'
+        ? { message: `Проверить нельзя: перебор альтернатив превысил ${SUBSET_LIMIT} поля` } : {}) });
+  }
+  return result;
+}
+
+/**
+ * Законный вызов, содержащий путь: сначала со значением генератора, затем с каждым годным значением других вариантов.
+ * Соседние снятые поля добавляются группами: отдельный путь может быть законен лишь вместе с ними.
+ * Не нашёлся при заведомо годном значении (значение генератора проходит ВСЕ объявленные ограничения отгруженной схемы
+ * на этом пути, либо значение взято у другого варианта) — отгруженный не принимает поле в этой форме; годного значения
+ * нет — подобрать не из чего.
+ */
+function findAlternative(full, mainArgs, path, removable, accept, good) {
+  const units = [...new Set([
+    ...removable.filter((unit) => !coversPath(unit, path)),
+    ...leavesUnder(full, path),
+  ])];
+  // Альтернатива строится от главного образца с возвращённым путём — ближайший законный вызов, а не произвольный.
+  const [generatorValue] = valuesAt(full, path);
+  // JSON-реестр иногда описывает массив id как string[], а исполняемый Zod требует UUID.
+  // Значение одноимённого одиночного id уже прошло отгруженный фильтр в основном вызове.
+  const siblingId = Object.entries(mainArgs).find(([key, value]) =>
+    path.endsWith(`${key}s`) && typeof value === 'string' && FORMAT_CHECKS.uuid(value))?.[1];
+  const values = [
+    ...(Array.isArray(generatorValue) && siblingId !== undefined ? [[siblingId]] : []),
+    generatorValue,
+    ...good.values,
+  ];
+  const missing = [...new Set(removable.filter((unit) =>
+    unit !== path && !relatedPaths(unit, path) && !hasPath(mainArgs, unit) && hasPath(full, unit)))];
+  // Поля отчётов часто законны только при другом значении переключателя (`mode=range`,
+  // `report=recipients`). Перебор подмножеств 15 соседних полей сначала расходовал лимит на
+  // нерелевантные сочетания. Пробуем каждый объявленный enum отдельно, затем пары enum;
+  // отсутствующие обязательные поля добавляем по адресным отказам отгруженного фильтра.
+  const enumChoices = [...good.shippedConstraints]
+    .filter(([key, constraint]) => key !== path && !key.includes('.') && !key.includes('[]') &&
+      typeof constraint.enum === 'string')
+    .map(([key, constraint]) => [key, constraint.enum.split('|').filter(Boolean)])
+    .sort((left, right) => left[1].length - right[1].length);
+  const minimalBase = Object.fromEntries(Object.entries(mainArgs)
+    .filter(([key]) => good.shippedConstraints.get(key)?.required === true));
+  const enumBases = [minimalBase, mainArgs, ...enumChoices
+    .filter(([key]) => hasPath(mainArgs, key))
+    .map(([key]) => withoutPath(mainArgs, key))];
+  const tryDirected = (candidate) => {
+    let current = candidate;
+    const seen = new Set();
+    for (let round = 0; round < MAX_ROUNDS; round += 1) {
+      const signature = JSON.stringify(current);
+      if (seen.has(signature)) break;
+      seen.add(signature);
+      const verdict = accept(current);
+      if (verdict.ok) return { kind: 'FOUND', args: current, verdict };
+      const required = [...new Set((verdict.refusals ?? [])
+        .map((refusal) => refusal.path)
+        .filter((missingPath) => missingPath !== null && !hasPath(current, missingPath) &&
+          hasPath(full, missingPath)))];
+      if (required.length > 0) {
+        current = required.reduce((args, missingPath) =>
+          withValueAt(args, missingPath, valuesAt(full, missingPath)[0]), current);
+        continue;
+      }
+      const conflicting = [...new Set((verdict.refusals ?? [])
+        .map((refusal) => refusal.path)
+        .filter((refusedPath) => refusedPath !== null && hasPath(current, refusedPath) &&
+          !relatedPaths(refusedPath, path)))];
+      if (conflicting.length === 0) break;
+      current = conflicting.reduce((args, refusedPath) => withoutPath(args, refusedPath), current);
+    }
+    return null;
+  };
+  for (const value of values) {
+    if (value === undefined) continue;
+    for (const base of enumBases) {
+      const start = withValueAt(base, path, value);
+      const direct = tryDirected(start);
+      if (direct !== null) return direct;
+      for (const [firstPath, firstValues] of enumChoices) {
+        for (const firstValue of firstValues) {
+          const first = withValueAt(start, firstPath, firstValue);
+          const oneChange = tryDirected(first);
+          if (oneChange !== null) return oneChange;
+          for (const [secondPath, secondValues] of enumChoices) {
+            if (secondPath === firstPath) continue;
+            for (const secondValue of secondValues) {
+              const twoChanges = tryDirected(withValueAt(first, secondPath, secondValue));
+              if (twoChanges !== null) return twoChanges;
+            }
+          }
+        }
+      }
+    }
+  }
+  const scopeChoices = path === 'value'
+    ? (good.shippedConstraints.get('scope')?.enum ?? '').split('|').filter(Boolean)
+    : [];
+  const bases = [mainArgs, ...scopeChoices.map((scope) => withValueAt(mainArgs, 'scope', scope))];
+  let tried = 0;
+  let limitExceeded = false;
+  for (const value of values) {
+    if (value === undefined) continue;
+    for (const base of bases) {
+      for (const subset of additionsUpTo(missing, SUBSET_LIMIT)) {
+        tried += 1;
+        if (tried > ALTERNATIVE_CANDIDATE_LIMIT) return { kind: 'SEARCH_LIMIT_EXCEEDED' };
+        const candidate = subset.reduce((args, unit) => {
+          const [siblingValue] = valuesAt(full, unit);
+          return withValueAt(args, unit, siblingValue);
+        }, withValueAt(base, path, value));
+        const found = findLegalCall(candidate, units, accept, [path]);
+        if (found?.limitExceeded) limitExceeded = true;
+        else if (found !== null) return { kind: 'FOUND', args: found.args, verdict: found.verdict };
+      }
+    }
+  }
+  if (limitExceeded || missing.length > SUBSET_LIMIT) return { kind: 'SEARCH_LIMIT_EXCEEDED' };
+  return { kind: good.values.length > 0 ? 'SHIPPED_FORBIDS' : 'VALUE_NOT_FOUND' };
+}
+
+const CHECKED_CONSTRAINTS = [
+  'type',
+  'enum',
+  'pattern',
+  'format',
+  'minimum',
+  'maximum',
+  'minLength',
+  'maxLength',
+  'minItems',
+  'maxItems',
+];
+
+/** Проходит ли значение на пути (и всё под ним) объявленные ограничения отгруженной схемы. */
+export function satisfiesShippedSchema(args, path, shippedConstraints) {
+  for (const [constraintPath, constraints] of shippedConstraints) {
+    if (!coversPath(path, constraintPath)) continue;
+    for (const value of valuesAt(args, constraintPath)) {
+      for (const kind of CHECKED_CONSTRAINTS) {
+        if (constraints[kind] !== undefined && violatesConstraint(kind, constraints, value)) return false;
+      }
+    }
+  }
+  return true;
+}
+
+/**
+ * Шаг 0: проверенные аргументы как отгруженный вызов. Поля, которых у отгруженного нет (только ветки v2), снимаются —
+ * отгруженный клиент их не пошлёт никогда; внутри свободного объекта (у отгруженного без перечня свойств) ничего не
+ * снимается. Исключение — новый переключатель, для которого исполнение v2
+ * доказывает смену метода/адреса: его сохраняем, чтобы получить явную невозможность образца.
+ *
+ * @param {Map<string, object>} shippedPaths пути отгруженной схемы (`schemaPathsOf`)
+ */
+export function prepareKnownArgs(known, shippedPaths, variant = {}) {
+  const shippedKeys = [...shippedPaths.keys()];
+  const prune = (value, prefix) => {
+    if (Array.isArray(value)) return value.map((item) => prune(item, `${prefix}[]`));
+    if (!isObject(value)) return value;
+    if (prefix !== '' && !shippedKeys.some((path) => path.startsWith(`${prefix}.`))) return value;
+    const out = {};
+    for (const [key, child] of Object.entries(value)) {
+      const path = prefix === '' ? key : `${prefix}.${key}`;
+      if (shippedPaths.has(path)) out[key] = prune(child, path);
+    }
+    return out;
+  };
+  let prepared = prune(known, '');
+  // Неизвестный отгруженной схеме переключатель маршрута нельзя тихо снять:
+  // после снятия проверялся бы export вместо inbox. Обычные новые фильтры
+  // по-прежнему снимаются. Сохраняем только доказанный прогоном v2 переключатель.
+  if (variant.acceptV2 !== undefined) {
+    const canonical = variant.acceptV2(known);
+    if (canonical.ok && routeShape(canonical.request) === variant.mainRouteShape) {
+      for (const path of generatedRoots(known, prepared)) {
+        const reduced = variant.acceptV2(prepared);
+        const candidate = withValueAt(prepared, path, valuesAt(known, path)[0]);
+        const restored = variant.acceptV2(candidate);
+        if (reduced.ok && routeShape(reduced.request) !== variant.mainRouteShape &&
+            restored.ok && routeShape(restored.request) === variant.mainRouteShape) {
+          prepared = candidate;
+        }
+      }
+    }
+  }
+  return prepared;
+}
+
+/**
+ * Проверенные значения, которые нарушают ограничение ОТГРУЖЕННОЙ схемы на пути, где сравнение схем объявило
+ * расхождение: форма ветки v2, которую отгруженный клиент послать не может.
+ */
+export function knownPathsViolatingShipped(known, schemaLag, shippedConstraints) {
+  const paths = new Set();
+  for (const row of schemaLag) {
+    const [path, kind] = row.path.split('#');
+    if (row.kind !== 'CONSTRAINT' || kind === 'required') continue;
+    if (valuesAt(known, path).some((value) => violatesConstraint(kind, shippedConstraints.get(path), value))) {
+      paths.add(path);
+    }
+  }
+  return [...paths].sort();
+}
+
+/** Копия проверенных аргументов со значениями генератора на путях. */
+export function withGeneratedValues(known, generated, paths) {
+  let out = known;
+  for (const path of paths) {
+    const [replacement] = valuesAt(generated, path);
+    if (replacement !== undefined) out = withValueAt(out, path, replacement);
+  }
+  return out;
+}
+
+/** Подтверждённое ограничение отгруженной схемы различается даже после предела перебора. */
+export function resolveShippedVariant({ outcome, known, generated, schemaLag, shippedConstraints, build, mainRouteShape }) {
+  if (!['SHIPPED_REJECTS_EVERY_SET', 'SHIPPED_COMBINATION_LIMIT'].includes(outcome.impossible?.reason)) return outcome;
+  const violating = knownPathsViolatingShipped(known, schemaLag, shippedConstraints);
+  if (violating.length === 0) return outcome;
+  // build исполняет оба фильтра. Подмена enum допустима только для того же метода и адреса;
+  // новый отчёт с отдельным адресом остаётся вариантом, которого отгруженный клиент не имеет.
+  const retry = build(withGeneratedValues(known, generated, violating));
+  if (retry.request !== undefined && routeShape(retry.request) === mainRouteShape) return retry;
+  return {
+    ...retry,
+    request: undefined,
+    omitted: [],
+    alternatives: [],
+    refused: [],
+    pathless: [],
+    absentKnown: [],
+    impossible: { reason: 'V2_ONLY_VARIANT', paths: violating },
+  };
+}
+
+/** Путь в отгруженной JSON-схеме инструмента. */
+export function schemaPathsOf(jsonSchema, label) {
+  return schemaConstraints(jsonSchema ?? {}, '', new Map(), 0, jsonSchema ?? {}, label);
+}
+
+/** Новые переключатели маршрута имеют точные решения; собравшийся вариант снимает прежнее объяснение. */
+export function variantExtensionFindings({ tools, extensions, shippedSchemas, localSchemas, variantsByTool }) {
+  const findings = [];
+  const caseKey = (tool) => tool.variant === undefined ? tool.name : `${tool.name}@${tool.variant}`;
+  for (const tool of tools) {
+    if (tool.shippedSampleImpossible?.reason !== 'V2_ONLY_VARIANT') continue;
+    const shipped = shippedSchemas.get(tool.name);
+    for (const path of tool.shippedSampleImpossible.paths) {
+      if (shipped?.properties?.[path] !== undefined) continue;
+      const key = `${caseKey(tool)}::${path}`;
+      if (extensions[key]?.kind !== 'V2_ONLY_VARIANT') findings.push(`${key}: нет решения о новом переключателе`);
+    }
+  }
+  for (const [key, row] of Object.entries(extensions)) {
+    if (row.kind !== 'V2_ONLY_VARIANT') continue;
+    const [variantKey, path] = key.split('::');
+    const tool = tools.find((item) => caseKey(item) === variantKey);
+    const shipped = shippedSchemas.get(tool?.name);
+    const current = localSchemas.get(tool?.name);
+    const canonical = variantsByTool.get(tool?.name)?.find((item) => item.variant === tool.variant)?.args;
+    if (tool?.shippedSampleImpossible?.reason !== 'V2_ONLY_VARIANT' ||
+        !tool.shippedSampleImpossible.paths.includes(path) ||
+        shipped?.additionalProperties !== false || shipped.properties?.[path] !== undefined ||
+        typeof row.variantValue !== 'string' || canonical?.[path] !== row.variantValue ||
+        !current?.properties?.[path]?.enum?.includes(row.variantValue)) {
+      findings.push(`${key}: строка нового переключателя протухла или не подтверждена схемами и вариантом`);
+    }
+  }
+  return findings;
+}