docx4j 17.3.6 транслирует w:framePr в fo:block-container absolute-position=fixed
(left/top) - до апгрейда текст фрейма шёл общим потоком у левого поля. Замер
реаудита (x=252pt) был для hAnchor=margin; фикстура frame-pr.docx пинит
hAnchor/vAnchor=page x=3600 -> текст на 180pt от края страницы, обычный абзац -
72pt от поля. Регрессия WordPdfConverterTest#framePr_positionedLikeWord.
Счётчики: фикстуры 14 docx, тесты 57/885 (догнаны до фактических).
Удаление правил Symbol/Field (делает сам экспорт 17.3.x) убрало два
хорошо покрытых класса и просадил branch-coverage 0.8505 → 0.8487 под
гейт JaCoCo 0.85. Добавлены тесты задокументированных, но не покрытых
веток WordPdfValidator#rasterArea (битые сигнатуры PNG/BMP по байтно,
короткие заголовки, JPEG: нет FFD8, мусор-маркер, обход DHT/C8/CC и
нетелевых RST/TEM, SOF0 без телеги) и null-контрактов
validate/checkPageCountDoc/isBinaryDoc. Регрессия —
WordPdfValidatorTest#validate_rasterGarbageHeadsAccepted,
#nullGuards_rejectBeforeWork, #validate_nullOptions_rejected.
checkDocxContainer получает бюджеты параметром; validate считает их из
ConvertOptions.maxMb()/maxPages(): clamp(maxMb×10MiB + maxPages×64KiB, 16MiB,
MAX_DECOMPRESSED_MB) и clamp(maxMb×4MiB + maxPages×32KiB, 4MiB,
MAX_DECOMPRESSED_XML_MB) (коэффициенты/полы — package-private константы
WordPdfConverter, compile-time инлайн — WordPdfValidator по-прежнему без
зависимости от docx4j). Константы WordPdfSettings — жёсткие крышки (публичный
API, защита JAXB DOM). Сообщения печатают вычисленный бюджет. Тесты: пол
(16 МБ при maxMb=1), масштабирование и крышка (64 МБ при maxMb=10); доки
синхронизированы.
Аудит потокобезопасности ядра: font()/regular()/... читали VARIANTS
(HashMap, пишется в init() под монитором BundledFonts.class) без
замка — публичный API гонял с init(). font() стал synchronized
(делегаты regular/bold/italic/boldItalic идут через него). Контракты
зафиксированы javadoc: restrictToBundled() рядом с идущей
конвертацией — только под монитором WordPdfConverter.class;
потокобезопасность GlyphFont (монитор of(), volatile cmap, внутренние
замки fontbox lockReadtable). Инвариант — AGENTS.md. Тест
concurrentFontApi_callsAllSucceed — 4 потока × 50 итераций font-API.
Регрессия — BundledFontsTest#concurrentFontApi_callsAllSucceed.
Публичный convert() теперь безопасен из нескольких потоков: секция после
валидации (мост .doc + convertToStream) выполняется под монитором класса —
общая FopFactory (per-render disableFontCache, имиджевые кеши) и её сброс в
finally больше не могут пересечься с параллельным рендером. warmup()
синхронизирован тем же монитором (реентельно). WordPdfValidator остаётся
до монитора: stateless, вызывается параллельно HTTP-потоками.
Регрессия — WordPdfConverterTest#concurrentConversions_twoThreadsBothSucceed.
Комментарии ConversionService/AGENTS/repo-map приведены к новому контракту.
Переиспользование FopFactory между конвертациями раньше запрещалось:
форк FOP копит на фабрике image-кеши (xmlgraphics-commons ImageCache:
imageInfos/images и ImageObjectCacheImpl), ключи записей — временные
файлы file:/tmp/<uuid>… с уникальным на конвертацию именем, попадания
не бывает никогда, а soft-ссылки не освобождаются при свободной куче
(2 ГБ фиксированная): после 30 конвертаций ~1,5 ГБ живых byte[]
против 17 МБ, рост live-кучи, Full GC.
Теперь фабрика одна на JVM, а каждая конвертация в finally вызывает
resetSharedImageCaches() — публичные clearCache() у ImageCache и
ImageObjectCacheImpl. Разбор шрифтов форка (GPOS, ~140k объектов)
теперь один раз на JVM. Замер после фикса: 16,8 МБ живых byte[],
heap used 89 МБ после 30 конвертаций, Full GC от нагрузки — 0.
Регрессии — WordPdfConverterTest#fopFactorySharedAcrossConversions,
#sharedImageCaches_clearedAfterConversion.
ChartImageHandler: для не-JPEG без кропа с ppi <= threshold (или без
размера в макете) PictureCompression.compress всегда возвращает null,
но сначала декодирует полный растр ImageIO — решение принимается по
26 байтам заголовка (PNG/GIF/BMP), растр не декодируется вовсе; JPEG
остаётся на штатном пути CR-029 (перекодировка «для размера» сохранена).
OleObjectNormalizer: детект <w:object — потоковым поиском окном 8 KiB
с перекрытием, без readAllBytes()+new String на каждую word/*.xml.
Heap: ENTRYPOINT -Xms2g -Xmx2g (вместо -XX:MaxRAMPercentage=70),
mem_limit 2g -> 3g (compose.yml, compose.dev.yml, прод-heredoc
main.yml) — фиксированный heap + запас под metaspace/native.
Отменённая ветка: переиспользование общей FopFactory между прогонами
копит шрифтовые данные форка FOP на каждый render (замер 2026-11:
после 30 конвертаций ~1,4 ГБ живых byte[] против 17 МБ при
per-conversion сборке, рост live-кучи, Full GC) — фабрика остаётся
per-conversion, инвариант зафиксирован комментарием.
GC-замер (java -jar, -Xms2g -Xmx2g, 30 конвертаций фикстур): young
5 против 7 на main, паузы 12,2 мс против 18,7 мс, Full GC нет на обоих.
Тесты: ChartImageHandlerTest +5 (PNG/GIF/BMP/JPEG/выше порога),
OleObjectNormalizerTest +1 (маркер через границу окна).
Мост .doc → .docx (internal/doc) и javadoc-контракты переводятся на
ConversionException; WordPdfValidator.checkPageCountDoc оборачивает отказ
моста в ValidationException с сохранением текста (вердикт «вход
некорректен» выносит только валидатор; глубина, ловимая лишь при
конвертации, становится 500 — как у .docx). Проверки ConvertController
переезжают на новый app-класс BadRequestException (400 с теми же
текстами), ApiExceptionHandler получает хендлер. Тесты моста доказывают
ровно тип (assertSame(ConversionException.class, ...)); новый регрессивный
WordPdfValidatorTest#checkPageCountDoc_brokenBridge_wrappedAsValidation.
Документация (AGENTS.md, docs/agent/doc-bridge.md) синхронизирована.
ConversionService в конструкторе ставит WordPdfConverter.warmup() головой
той же однопоточной очереди: первый реальный запрос после деплоя — за
прогретым ядром (~50–300 мс вместо 1,4–1,9 с) и сериализован с
конвертациями. Тесту сатурации нужен сентинел после конструктора: прогрев
занимает слот воркера головой очереди.
Первая конвертация после старта JVM стоит 1,3–1,7 с (JAXB/XSLT/FOP/классы),
её платил первый запрос после деплоя. warmup() прогоняет весь пайплайн на
минимальном docx, собранном в байтах (фикстуры не задействованы), и греет
Java2D/PNG-энкодер для пре-рендера диаграмм. Идемпотентен (volatile флаг),
не бросает (провал — warn в JUL), артефакты отбрасываются. Ядро само себя
не прогревает — момент прогрева решает приложение.
Прогретая первая конвертация ru-plain.docx: 100 мс против ~1,4 с холодную.
BestMatchingMapper (static) при первом касании сканирует системные шрифты
и все jar'ы classpath'а (~100–140 мс на JVM плюс память реестра), а
BundledFonts.restrictToBundled() перед каждой конвертацией всё найденное
выбрасывает. Гейт-свойства discoverPhysicalFonts/discoverJarFonts ставим
в false в static-блоке WordPdfConverter (инициализация класса
предшествует первому new BundledFontMapper()). discoverJarFonts("fonts-symbol")
свойством не гейтится — символ-шрифт регистрируется и снимается restrict'ом
как раньше; живой реестр (Panose-путь) после restrict идентичен, всё
незамапленное — финальный fallback DejaVu Sans (прежняя стратегия).
DrawingPreRenderer.swapForPicture вставляет media-часть вручную
(newPartForContentType → setBinaryData → rels.addPart, имена
/word/media/chart-*): createImagePart писал temp-файл и декодировал
PNG обратно ради mime/размеров, которые нам и так известны.
ChartImageHandler (foSettings.setImageHandler) возвращает null из
compressedVariant для chart-* — «Compress Pictures» не ресемплит и не
декодирует наши 300-dpi растры; медиа документов остаются в штатном
docx4j-режиме. Замер (25 фикстур × 6 прогонов): chart-types.docx
657→507 МБ alloc (тёплый), суммарно 11640→10604 МБ, прочие 23 файла
±0%; ретеншн не изменился (144 MiB после GC), temp-файлов 0.
Регрессии: chartMedia_notDownsampled, DrawingPreRendererTest,
ChartImageHandlerTest.
- Правило 9 HiddenTextNormalizer: скрытые раны (прямой truthy w:vanish или
rStyle на vanish-стиль по цепочке w:basedOn) вырезаются до load() — Word
скрытое не печатает, стилист docx4j vanish не читает (скрытое утекало в PDF).
- Правило 10 RubyNormalizer: w:rubyBase/w:rubyBaseText разворачиваются,
w:rt/w:rubyPr/w:rubyAlign вырезаются — схема docx4j не биндит rubyBase/rt,
unmarshaller терял текст базы до XSLT (надстрочница — принятая деградация).
- AUDIT-FIX-2 в вендорном docx2fo.xslt: шаблоны w:moveFrom/w:moveTo/w:bdo/w:dir
(plain-text passthrough вместо catch-all); гейт vendoredXsltTracksJarCopy
обобщён на оба AUDIT-FIX-региона.
- Пиннинг работающих фич e2e-синтетикой: сноски/концевые, /URI-аннотации,
PAGEREF (complex + вложенный в TOC) и DATE (кэш заменяется живым), titlePg,
vMerge, block sdt, wps:txbx, OMML (пиксели), highlight/shd (фон рисуется —
прежняя запись в AGENTS.md о «fo:inline без фона» ошибочна, исправлена).
- AGENTS.md: правила 1–10, OLE=правило 11, инвентарь аудита, счётчики
(core 51/825, всего 57/868).
TTP-абзац каждой строки несёт свой sprmTDefTable; автомат использовал только
сетку первой строки → объединённая ячейка получала tcW первой колонки и
рендерилась пол-width с лишней вертикальной чертой в строке. Теперь rowXml
строит tcW/gridSpan из собственной сетки строки, согласованной с tblGrid
(ECMA-376 §17.4.65); при невыровненных границах — прежняя индексная выдача.
Регрессия — WordPdfConverterTest#docMergedTableRow_fullWidthNotSplit,
юниты — DocToDocxFormattingTest#mergedRow_gridSpanAndWidth,
#misalignedRow_fallsBackToColumnWidths.
Word выносит grpprl абзаца за FKP-страницу PAPX в Data-поток: одиночный
Prl sprmPHugePapx (0x6646) и цепочку sprmPTableProps (0x646B). Мост
читал сырой указатель → InTable/TTP/TAP терялись, строки таблиц с
huge-PAPX разваливались в плоские абзацы (жалоба на docTest.doc).
Новый класс PrcData.resolve(data, grpprl): union цепочки и исходных
Prl на позиции указателя; guard'ы (ptr за Data, cb вне [1, 0x3FA2],
цикл — бюджет 32 PrcData) — останов без исключения. Без указателей →
тот же массив. Отступление от §2.6.2 (обрыв за PTableProps) обязателен:
Word пишет после PTableProps легаси-зеркало с единственным TDefTable
(samples/ru-table-image.doc), а sprmTInsert из PrcData конвертер не
читает. Точка подключения единственная — DocxBody.buildRange.
Тесты: PrcDataTest (13 юнитов, byte[]-крафт), DocToDocxFormattingTest
#hugePapxRowMark_closesRowWithGridFromPrcData (POIFS-.doc, сетка из
цепочки). Живая проверка develop/docTest.doc: таблицы «Таблицы»
структурированы, фантомных рядов и плоских абзацев нет.
- контракт нормализаторов: STEP у 8 rewrite-нормализаторов, у OleObjectNormalizer нет (лямбда в normalizers())
- число тестов: 582 @Test (core 540, было 537)
- job deploy: подсеть прода 10.112.0.0/24, бинд gateway 127.0.0.1+$DEPLOY_HOST:9010, resolver 10.112.0.1
- compose.yml: springdoc выключен env-переменными (в dev — включён)
- main.yml: проверка Variables (включая новую PIP_INDEX_URL) — до Setup venv (fail-closed);
pip install только с индекса Nexus (-i), PIP_TRUSTED_HOST вырезается из URL,
--timeout 60 --retries 5 на холодный промах прокси
- GITEA-vars.md: Variable PIP_INDEX_URL + раздел «Nexus: pypi-proxy» (репозиторий,
роль pypi-anonymous, Anonymous User Role IDs) — заводятся до мержа
- AGENTS.md: PIP_INDEX_URL в перечень Variables
- readTitle: пустой/пробельный c:title (или val=0 без c:title) — автозаголовок
Office (MS-OI29500 §2.1.1561(a)): одиночный ряд с именем → имя ряда любого
типа графика, иначе плейсхолдер; раньше имя ряда — только у круговых
- autoTitleDeleted (§21.2.2.7) применяется только при отсутствии c:title
(MS-OI29500 §2.1.1431(a)) — явный заголовок показывается при любом флаге
- регрессии ChartSpecTest: emptyTitleSingleSeriesBar_usesSeriesName,
deletedTitleWithText_stillShown, deletedTitleValOmitted_stillShown,
noTitleElement_*; AGENTS.md приведён в соответствие
- Кернинг: DejaVu Sans/Serif имеют legacy kern-таблицу, но она ключована
glyph id вне cmap (2568/2727 пар без Unicode-маппинга, A->V нет) — FOP
такие пары отбрасывает; замер конвейера: A->V = A->A и у Carlito, и у
DejaVu (7.524pt@11pt). Вывод «не кернит ни одно семейство» подтверждён,
причина «все шрифты GPOS-only» была неточна — исправлено в AGENTS.md
- «Word ≈13.9pt»: заявленное «пиксельное округление 18px@96dpi» —
нерепродуцируемая реконструкция (артефактов замера нет); переформулировано
в AGENTS.md, LayoutPostRenderer и WordPdfConverterTest