docs(docs): RUST.md §10.10 R4.8 record (deleted, replaced, kept with reasons, census, non-regression table, risks, R5 prerequisites); CLAUDE.md, README, WORKSPACE, packages/README, TEST_STRATEGY, PDF-FORMAT, DEPLOY rollback R4 note and module size, hardening §5 pdf-lib closed, fixtures README, CHANGELOG R4 entry; TODO R4.8 closed; memory BDR-064, journal

This commit is contained in:
bchanot committed 2026-10-19 12:17:02 +02:00
1 parent e88769a707
commit f36dbdd4ae
13 files changed
+238 -62

No files matched your search

+27 -20
View File
@@ -1,9 +1,11 @@
# PDF format and report archive
A Faunosteo PDF is both a document for the reader and an archive of the
bilan. The engine lives in `packages/pdf` (`@faunosteo/pdf`) and renders from
explicit inputs only: no network, no browser DOM, no access to the current
catalog. The attachment carries everything a future reader needs to
bilan. The engine lives in the Rust core (`crates/core/src/pdf`, reached
through the wasm module in the browser and natively by the tools; the
TypeScript `packages/pdf` it reproduced byte for byte was deleted at R4.8,
`docs/development/RUST.md` §10) and renders from explicit inputs only: no
network, no browser DOM, no access to the current catalog. The attachment carries everything a future reader needs to
re-render the bilan when the anatomical sheet, the catalog, the labels or the
branding have changed since the export. Design record:
`docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md`.
@@ -19,8 +21,9 @@ branding have changed since the export. Design record:
asset), then zones, findings grouped by finding zone, free findings,
severity, comment.
- Conclusion page: conclusion, recommendations, next appointment.
- Fonts: pdf-lib StandardFonts Helvetica, Helvetica-Bold (body) and
Times-Roman (headings), WinAnsi encoding. Every printed string goes through
- Fonts: the standard Type1 fonts Helvetica, Helvetica-Bold (body) and
Times-Roman (headings), WinAnsi encoding, measured with the AFM widths
pdf-lib 1.17.1 used (`crates/core/src/pdf/write/afm_data.rs`). Every printed string goes through
`safeText`: control characters are stripped and any glyph WinAnsi cannot
encode becomes `?` (en and em dashes, accented letters, `•`, `·` are fine;
`⚠` is not, hence the `(!)` vet-referral marker).
@@ -44,7 +47,7 @@ branding have changed since the export. Design record:
One native embedded file (`EmbeddedFiles`, `AFRelationship /Data`) named
`osteo-report.json`, MIME `application/json`, description
`Faunosteo report archive v1`, Flate-compressed by pdf-lib. Pretty-printed
`Faunosteo report archive v1`, Flate-compressed (zlib level 6). Pretty-printed
JSON, camelCase keys (the sheet document inside keeps its own snake_case
schema):
@@ -227,15 +230,16 @@ The same caps are checked at export, so an export can never write a file its
own reader refuses.
The branding URL rule exists because a URL is written into every page's
link action: pdf-lib does not escape a literal string, so the engine writes
the URI as a hex string and the schema refuses the characters that could
close a literal. The export re-validates the branding and the labels it
link action: a literal string is not escaped (pdf-lib did not, the core
does not either), so the engine writes the URI as a hex string and the
schema refuses the characters that could close a literal. The export re-validates the branding and the labels it
receives (`ArchiveExportError('branding_invalid')` before any page is
drawn), even from an archive that passed the reader. The URI itself is the
hex form of the URL's ASCII bytes (`<68747470…>`), not UTF-16 with a BOM,
so readers that take `/URI` as raw bytes (poppler) follow it. A PNG logo is
checked before pdf-lib's decoder (UPNG) sees it, because that decoder trusts
its input: it sizes its bitmap from whatever IHDR claims, its `inflateRaw`
checked before the decoder sees it (the core's decoder reproduces UPNG's
acceptance, the decoder pdf-lib used, so that an archived logo decodes to
the same planes); the gate exists because that decoder trusted its input: it sizes its bitmap from whatever IHDR claims, its `inflateRaw`
never checks the input bound (a truncated or crafted IDAT stream makes it
read past the buffer and never return), and it scans text chunks for a NUL
byte that may be missing. The gate therefore validates, in order: the
@@ -247,10 +251,11 @@ sizes are not computed); an expected raw scanline size,
`(ceil(width × bits per pixel / 8) + 1) × height`, of at most 16 MiB, the
attachment cap the native inflater enforces (4096² at 8-bit RGBA is 67 MB
of scanlines and is refused; a 512 px wide logo is under 1 MB). That cap
bounds what is inflated, not what pdf-lib's decoder then allocates: the
decoder still expands any accepted image to a 32-bit RGBA buffer, so the
4096² pixel cap is what bounds memory (about 430 MB peak measured with four
4096² logos; real logos are 512 px wide). Then the chunk list, which must end on an empty `IEND`
bounds what is inflated, not what the decoder then allocates: the decoder
still expands any accepted image to a 32-bit RGBA buffer, so the 4096² pixel
cap is what bounds memory (about 430 MB peak measured with four 4096² logos
on the TypeScript engine; real logos are 512 px wide; the core frees the
planes as soon as the image object is written). Then the chunk list, which must end on an empty `IEND`
that closes the file and may hold only the chunk types the decoder reads by
fixed offsets or by declared length (`PLTE`, `tRNS`, `IDAT`, `IEND`,
`gAMA`, `cHRM`, `sRGB`, `sBIT`, `pHYs`, `bKGD`): a second IHDR, an APNG
@@ -271,11 +276,13 @@ fallback text and the export reports `logo_failed`.
reader in a worker since R4.3) and the `report:compare` tool (the same
reader, natively, since R4.7) read the attachment by byte scan, so a
crafted object stream is never inflated (tested with a 64 MiB bomb:
milliseconds, no memory growth). pdf-lib stays on the export side, on trusted inputs, and
in tests that inspect exported files. What remains before external users
(`docs/development/PDF_IMPORT_HARDENING.md` §5): a Worker or server-side
budget for any path that still parses PDF objects, the pdf-lib dependency
decision, and read-side caps on report collections.
milliseconds, no memory growth). No PDF library remains in the repository
since R4.8: the core writes the files, the tests read them back with a
reader of the writer's own format (`apps/app/tests/helpers/pdfFile.ts`).
What remains before external users
(`docs/development/PDF_IMPORT_HARDENING.md` §5): the server-side budget
decision for any future path that parses PDF objects, and read-side caps
on report collections.
- The scanner reads what is in clear: an attachment whose stream dictionary
is malformed beyond `/Length` and `endstream`, or an encrypted file, yields
no candidate (`no_attachment`), as the previous reader did in practice.