feat(mcp): гарды зеркал реестра + write-целостность (#494) #513

Merged
vvzvlad merged 5 commits from feat/494-mcp-registry-guards into develop 2026-07-12 04:03:45 +03:00

5 Commits

Author SHA1 Message Date
agent_coder bc433d12e6 fix(mcp): ревью #513 — гонка LRU-эвикции + доводки контракта/доков
WARNING [stability]: эвикция могла убить ЧУЖУЮ ещё-connecting сессию как
idle-жертву — isBusy()=false во время open(), сессия вставлена в мапу до
await open(); параллельный acquire на ДРУГУЮ страницу при насыщении выселял
её → спурьёзный reject не-начатой записи / старвейшн новых записей. Фикс:
idle-victim скан теперь  — connecting
падает в last-resort oldestBusy, честный idle по-прежнему предпочитается,
кап держится, коалесинг того же ключа (per-page lock) не задет. Тест на
интерливинг (connecting не выселяется под насыщением), mutation-verified.

Доводки (проза, логику не меняют): drawioCreate description (nodeId:null на
nested-вставке); forward-коммент у writeWithCollabAuthRetry (ретрай только
auth; при расширении — проверять isCollabIndeterminateError, #435); хедер
comment-anchor (все 4 точки делегируют в resolveAnchorSelection); CHANGELOG.

Ребейзнут на develop (волна 1 смержена): только 4 коммита #494.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-12 00:03:59 +03:00
agent_coder 141ebb4864 fix(mcp): LRU-эвикция не реджектит чужой in-flight mutate как failure (#494)
Коммит 4. При достижении cap реестра live-сессий эвиктился LRU-кандидат через
destroy(), что реджектило его in-flight mutate терминальной ошибкой. Но update
такого mutate мог УЖЕ дойти до сервера и персиститься → эвикция превращала
удачную запись в ложный proval → retry-склонный агент повторял запись →
ДУБЛИКАТ (тот же механизм, что в инциденте #435).

Правка:
- цикл эвикции теперь ПРЕДПОЧИТАЕТ idle-жертву: идёт по LRU-порядку, пропускает
  busy-сессии (isBusy() — есть in-flight mutate) и эвиктит старейшую idle;
- если ВСЕ сессии busy (эвикция неизбежна для приёма новой записи) — эвиктит
  LRU busy через evictForCap(), который реджектит in-flight op ПОМЕЧЕННОЙ
  ошибкой INDETERMINATE «write may have applied — verify before retry», а не
  плоским failure. Маркер collabIndeterminate + guard isCollabIndeterminateError
  (симметрично isCollabAuthFailedError), чтобы «проверь перед ретраем» можно
  было отличить от чистого провала.

Тесты (мутационные): busy LRU-сессия сохраняется, эвиктится younger idle, и её
запись доезжает на ack; when-all-busy — эвикция реджектит запись именно
INDETERMINATE-ошибкой с маркером и текстом verify-before-retry.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-11 23:46:37 +03:00
agent_coder 045a0afaad fix(mcp): drawioCreate — успех с warning на вложенной вставке, а не throw (#494)
Коммит 3. При вставке диаграммы во вложенный контейнер (анкор внутри
callout/ячейки таблицы) узел УЖЕ записан и закоммичен мутацией, но тул кидал
ошибку «no addressable #<index> handle». Retry-склонный агент воспринимал это
как провал записи и повторял drawioCreate → ДУБЛИКАТ диаграммы (тот же класс
double-apply, что в инциденте #435).

Правка: ветка insertedIndex<0 возвращает success:true с nodeId:null и
warning'ом «written NESTED, saved — do NOT re-create; re-read via
getOutline/getPageJson (attachmentId …)» вместо throw. Запись подтверждается,
агент знает, что хендла нет и как перечитать — и не ретраит приземлившуюся
запись. nodeId стал string|null в drawioCreate и наследующих drawioFromGraph/
drawioFromMermaid (там тот же путь) + в интерфейсе IDrawioMixin.

Мок-тест: вложенная вставка не кидает, отдаёт success/nodeId:null/warning и
пишет диаграмму РОВНО один раз вложенной (краснеет, если вернуть throw).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-11 23:46:37 +03:00
agent_coder be433d40f0 refactor(mcp): гарды остальных зеркал реестра — проза, ярлыки, зонды, счётчик (#494)
Коммит 2. Каждое ручное зеркало получает настоящий гард/деривацию/parity-тест
вместо комментария «mirror this»:

- ROUTING_PROSE → ОБРАТНЫЙ гард (server-instructions.ts): прямой уже покрыт
  генерируемым <tool_inventory> (каждый зарегистрированный тул в списке); теперь
  `unregisteredProseToolMentions` краснеет, если проза ссылается на
  несуществующий/переименованный тул (camelCase-токены прозы ⊆ реестр, минус
  явный список не-тул-терминов PROSE_NON_TOOL_TERMS). Раньше мёртвая ссылка в
  прозе не краснела. Мутационный тест: `getPageContentz` ловится.

- LABELS экспорта чата (chat-markdown.util.ts) → parity-тест: каждый ключ-ярлык
  обязан быть реальным in-app тулом (иначе переименованный тул молча
  сваливается на generic «Ran tool <name>»), и оба языка (en/ru) размечают
  ОДИН набор тулов.

- зонд comment-signal ×2 (оба хоста) → общий `createListCommentsProbe` в
  packages/mcp: index.ts и ai-chat-tools.service.ts (через loader) строят
  tracker.probe из ОДНОЙ фабрики — тела больше не могут разойтись (например,
  один считает resolved-комментарии, другой нет). Проброшен через loader-границу
  как опциональный (отсутствует на устаревшем билде → сигнал выключен).

- countAnchorMatches (comment-anchor.ts) → делегирует решение
  exact-wins/strip-fallback единственному резолверу resolveAnchorSelection
  вместо параллельной копии; поведение идентично (rawCanAnchor ⟺ rawCount>0),
  parity-тест по корпусу краснеет при расхождении count↔resolve.

- normalize+sha256 ×2 (gen-registry-stamp.mjs + docmost-client.loader.ts):
  зеркало УЖЕ закрыто cross-impl parity-тестом (CROSS_IMPL_TREE/EXPECTED
  проверяется с обеих сторон) — критерий issue «либо parity-тест» уже выполнен;
  извлечение общего модуля через границу пакета/билд-шага регрессионно-опасно
  для load-bearing integrity-проверки (#486), поэтому оставлено как есть.

Тесты: mcp node --test unit+mock зелёные (844); затронутые server-specs
(chat-markdown, comment-signal-inapp, loader, service, tiers, contract, cap)
зелёные (351).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-11 23:46:37 +03:00
agent_coder e56a05926d fix(mcp): registration-time assert — каждый не-inline спек регистрируем (#494)
Коммит 1. Спек без execute падал по-разному на двух хостах: MCP-хост
(index.ts) в цикле регистрации делает `mcpExecute` иначе `spec.execute!` —
без execute это TypeError в момент ВЫЗОВА тула (то есть в проде, только когда
модель выберет именно этот тул); in-app-хост (ai-chat-tools.service.ts) делает
`inAppExecute ?? execute`, затем `if (!run) continue` — то есть МОЛЧА роняет
тул, он просто исчезает у агента без единой ошибки.

Комментарий «mirror this» гардом не считается: закрываем зеркало настоящим
структурным assert'ом. `assertEverySpecIsRegisterable()` гоняется при загрузке
модуля tool-specs на ОБОИХ хостах (оба его импортируют) и кидает исключение,
если не-inline спек, который хост регистрирует, не несёт исполнителя для этого
хоста — латентный рантайм-TypeError / тихий дроп превращается в громкий отказ
на старте. `inlineBothHosts` освобождён (оба хоста регистрируют его inline,
execute у него намеренно нет); `inAppOnly`/`mcpOnly` проверяются только для
своего хоста.

Тест по реестру с мутационной проверкой: синтетические плохие реестры
(без execute; inAppOnly без inAppExecute) обязаны кидать, а mcpExecute-only /
inAppExecute-only / inlineBothHosts — проходить. Часть (б) — assert
объявления write-класса — уже приземлилась в #489.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-11 23:46:37 +03:00