Merge chore/rust-r4-plan into develop
ci / rust (push) Canceled after 0s
ci / check (push) Canceled after 0s
ci / docker (push) Canceled after 0s
ci / supabase (push) Canceled after 0s

This commit is contained in:
bchanot committed 2026-10-18 04:43:08 +02:00
commit ae17097afb
5 files changed
+393

No files matched your search

+7
View File
@@ -436,3 +436,10 @@ Status: closed; R3 still awaiting owner LAN confirmation, not merged, R4 not sta
Owner brief 2026-10-16 + AskUserQuestion: (1) Home import also takes JSON rescue copy: sniff first KiB (`%PDF-` → PDF; `{` / .json → copy), cap MAX_ATTACHMENT_BYTES 16 MiB before read, fatal UTF-8, pure `readRescueCopy` → core `draft.restore` (no JS parse), then existing hydrateImport branch; UNREADABLE_DRAFT_KINDS → `invalid_copy`. (2) `internal` reading draft → held `engine_failure` row (+ archive companion), `TrapMemory` keyed on (draft, archive) pair: no re-read by mount / New report / Import, only panel Retry (`retryTrapped`); any discard clears; `held_blocked_engine` alert. SUPERSEDES BDR-055 "never held" for `internal` only (`core_unavailable` etc. stay FAILED). (3) ReplaceSessionDialog (Annuler / Ouvrir le bilan en cours / Remplacer, copy when unsaved) on New report submit + Home pick when report in memory or draft slot; Home picker clicked synchronously. (4) `useUnsavedGuard` once in App. Commit 9bd9aca.
Alt rejected: new store action openCopy (dup of hydrateImport, session change before validation); JS JSON.parse of copy (depth; core reads raw text); copy cap MAX_PDF_BYTES (50 MiB file cap, not JSON bound); trapped memory on draft text only (archive parsed in same call); fixing GC finalizer via glue internals.
Status: closed; R3 awaiting owner LAN validation, not merged, no R4, release 0.2.0 untouched.
## BDR-057 | 2026-10-18 | R4 plan validated: module workers, incremental export in main instance, JSON memory guard gated at R4.2
Context: R4.0 plan rev 2 (`.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md`: options §A.2, conditions §A.6), 3 challengers, owner approval 2026-10-18.
Decision: OD-1 module workers everywhere; import needs Firefox 114 (today it already needs DecompressionStream: Firefox 113, Safari 16.4); import support documented per browser apart from app support, from real checks. OD-2 incremental ExportSession in main instance: PDF + one decode ≈ 0.37 MB/view vs TS ≈ 3.8 MB/view (RGB planes held until save) vs two calls ≈ 0.91; offline export kept; cleanup on error/cancel. OD-3 JSON value budget in linear pre-scan + module `--max-memory`, thresholds from R4.2 reproducible measurements; not shown → stop before R4.3 import switch. OD-4 overwritten duplicate key holding lone surrogate refused, file untouched. OD-5 PDF crash/timeout `error_generic`, copy crash/timeout `error_core_unavailable`, kinds keep technical / resource / invalid apart. OD-6 J1 matrix exact, unrun device never reported validated. OD-7 ~5 MB fixtures, no real data in git.
Alt rejected: classic iife worker for Firefox 102-113 (dev/prod split for dead versions); two-call export (all PNGs in linear memory); disposable export worker (asset fetched at export breaks offline, protocol cost); throwaway main-thread instance (glue retains instances, LRN-060); own lossless JSON reader (R2 rejection holds).
Status: active. Order: plan merge → Safari download bugfix (owner validation) → feature/rust-r4-pdf-core → R4.1.
+4
View File
@@ -273,3 +273,7 @@ feature/rust-r3-anatomy-core: plan rev 2 after 3 challengers (32 findings; block
Owner brief: 5 checks before R3 close. Copy round trip proven, no in-app restore → Home import reads copy via draft.restore. Loop: fuzz 37k 0 traps (OOM ~50 MB only) → defended: trapping pair held in panel, re-read only on Retry. Work loss: guard app-wide, replace dialog on New report / Import. GC finalizer harmless, bounded, recorded. 9bd9aca; verifier 10/10, security PASS, check:all green. BDR-056, BLK-012, LRN-058, EVAL-024. R3 not merged (LAN pending), no R4, no release, no deploy.
- 2026-10-17 owner LAN acceptance R3: all functional + graphical tests passed, go to merge. Docs: RUST.md status (R2, R3 validated), §9 status, CLAUDE.md, CHANGELOG heading, README rescue copy bullet (copy ≠ archive of record) → db8c0ef. `gitflow finish` → develop 8df964b (pushed, branch deleted local + origin). check:all green on develop (Rust, wasm, Node 1015 tests incl. app 405, build, Docker app + worker). Residuals stay in BLK-011/BLK-012. R4 not started; release 0.2.0 untouched; no deploy. Waiting owner instructions.
## 2026-10-17 (R4.0 plan)
Owner go R4.0 (A1-A13: one branch + J1, old PDFs preserved, years 0-99 kept, Producer/Creator Faunosteo, goldens/r4, 0 px diff, import message kept + kinds split, copy via worker, Firefox/WebKit, report:compare name, TTF/scope_disclaimer/caps out, WASM stop, real PDFs). chore/rust-r4-plan: plan rev 1 → 3 challengers (19 major, 0 fatal) → rev 2. Facts: Rust lossy UTF-8 = TextDecoder (200,015 cases, 0 diff); serde_json refuses 1e400 (JS → null) → rewrite; TS embedPng holds RGB planes until save (≈ 3.8 MB/view) → session ≈ 0.37 MB/view; import already needs DecompressionStream (Firefox 113, Safari 16.4); glue module record retains instances (no throwaway instance). Firefox 157 Playwright OK, WebKit needs 2 apt libs. No code. Stop: owner validation, OD-1..OD-7.
+12
View File
@@ -454,3 +454,15 @@ Apply: R4 PDF worker failure states, Step 8 avatar upload errors, any capped ret
- User text into i18n templates: `.replace(re, () => value)`; string replacement expands `$&`/`$'`.
- Picker opened from a confirm dialog: call `input.click()` synchronously in the confirm handler (user activation, WebKit).
Apply: any export/backup feature, R4 PDF reader worker failures, Step 13 uploads.
## LRN-059 | 2026-10-17 | Rust `from_utf8_lossy` matches TextDecoder; serde_json differs from JSON.parse on overflow and surrogates
- `String::from_utf8_lossy` after stripping one BOM = `new TextDecoder().decode()` (non-fatal): 200,015 random + edge byte strings (overlong, UTF-8 surrogates, truncated, double BOM), 0 diff. Parity holds on tested sequences, not proven in general.
- JSON.parse vs serde_json: `1e400` → JS Infinity (JSON.stringify writes `null`), serde_json "number out of range"; lone surrogate escape kept by JS, refused by serde_json; duplicate key last value at first position in both (preserve_order). A JS path that did parse → stringify has side effects (overflow → null, dropped duplicates): reproduce them or declare them.
Apply: Rust ports of JS readers of untrusted text (R4 PDF reader, Step 13 uploads, Step 15 server validation).
## LRN-060 | 2026-10-17 | wasm-bindgen glue retains its instance until reload; only a terminated worker frees linear memory
- `--target web` glue keeps the instance in module scope (`let wasm`, `__wbg_finalize_init`); ES module records are never unloaded, so each fresh glue import (`?instance=n`) keeps its old instance and memory (BLK-012: dead instances retained until reload). Linear memory never shrinks.
- Memory-heavy one-shot work: reuse the long-lived instance (high-water kept until reload) or run in a Worker terminated after (everything freed). A "disposable instance" on the main thread is a leak, not a release.
Apply: R4 import worker and export placement, any future in-browser wasm batch job.
+13
View File
@@ -204,6 +204,19 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo
- [x] R3 final checks 2026-10-17 (owner brief 2026-10-16): rescue copy importable from Home, trapping draft held (no reload loop), replace confirmation, guard app-wide → 9bd9aca (BDR-056, BLK-012); verifier CONFORME 10/10, security PASS, check:all green; residuals in BLK-012
- [ ] R3 follow-ups kept by the owner (2026-10-15): worker TLS exercised against a real HTTPS endpoint before the deployment that needs it; roxmltree limits + SVG prescan (pin the iterative release when published); Firefox/WebKit check; SVG references across drawings scoped per view before community uploads (Step 13); WASM size margin (396 of 600 KB) before R4; TypeScript PDF sanitiser still present until R4
- [ ] R4 pdf core: reader (Web Worker, BLK-009 browser measurements) + writer (`pdf-writer`, Std14 AFM, draw log; lines/rects/colours golden frozen with the TS engine first, D-R2) + `report-compare` tool; `packages/pdf` deleted; N-1 scanner reads R4 PDFs
- [x] R4.0 plan (owner go 2026-10-17, arbitrations A1-A13): `.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md` rev 2 after 3 challengers (correctness 6 major, robustness 10 major, simplicity 3 major; none fatal) on chore/rust-r4-plan; Playwright Firefox 157 installed + proven, WebKit 27.2 downloaded (owner: `sudo apt-get install libevent-2.1-7t64 libmanette-0.2-0`); validated by the owner 2026-10-18 with conditions (plan §A.6, BDR-057)
- [ ] after validation: finish chore/rust-r4-plan into develop (owner signal), Safari PDF download fix (separate bugfix, owner go), then cut feature/rust-r4-pdf-core
- [ ] R4.1 freeze (O1-O13, ledger, browser harness, TS baselines)
- [ ] R4.2 reader (cargo + wasm, differential, OD-3 thresholds confirmed with owner before R4.3)
- [ ] R4.3 import worker + rescue copy (B.1.5, OD-1 applied, browser proof per slice from here)
- [ ] J1 owner checkpoint (plan A.4)
- [ ] R4.4 layout → draw log
- [ ] R4.5 serialiser (pdf-writer, self-check, from_envelope)
- [ ] R4.6 app export (session in main instance, owner phone check of L)
- [ ] R4.7 report-compare in Rust
- [ ] R4.8 deletions + docs + ledger census
- [ ] R4.9 verifier + security + owner final acceptance → merge on owner signal
- [ ] outside R4 (owner 2026-10-17, non-blocking): worker container ignores SIGTERM (Docker kill after 10 s; chore, e.g. `init: true`); README test counter stale (367 vs 1,015)
- [ ] R5 curation pipeline + importer + upload tool: seed golden regenerated once (new `documentSha256`, D-R5), `packages/anatomy` + `packages/domain` deleted, docs map; all before Step 13
- [ ] separate chore (D-R7): form constraints module + PGlite `pg_constraint`/config.toml parity test
- [ ] Release 0.2.0 (branch release/0.2.0 = Steps 3–6, version.txt + package versions 0.2.0, CHANGELOG [0.2.0] 2026-10-11): deploy-trigger check done 2026-10-12 (CI = branches main/develop only, no tag trigger, no deploy job, docker job builds `faunosteo:ci` locally; hooks push only; DEPLOY.md deploy = manual on the VPS). Default 0.2.0 build carries NO sheet (SHEET_BUNDLE=none) → the live local tool must not be redeployed from main without `--build-arg SHEET_BUNDLE=draft`. Finish via /release-candidate (finish + tag span, tag push on explicit go); CHANGELOG back-merge conflict expected (Unreleased Step 7 above [0.2.0]). Awaiting the user's go.
@@ -0,0 +1,357 @@
# PLAN: Rust R4, PDF core (reader in a disposable worker, writer, report-compare), `packages/pdf` deleted
- date: 2026-10-17 | rev 2 (after 3 plan challenges: correctness CONCERNS (6 major, 8 minor), robustness CONCERNS (10 major, 12 minor), simplicity CONCERNS (3 major, 9 minor); log in §B.12) | branch: `chore/rust-r4-plan` (plan only); code later on `feature/rust-r4-pdf-core`, one merge
- spec: owner briefs 2026-10-17 "Préparation de R4" and "Autorisation de préparation R4.0" (arbitrations A1 to A13, §A.0); `docs/development/RUST_ARCHITECTURE_REVIEW.md` I.2, II.2 rows "pdf reader", "pdf writer", "report-compare", III.3, VI.1 to VI.4, D-R2, D-R3, D-R11, D-R12, D-R14; `RUST.md` §8.3, §8.7, §8.8, §9.4, §9.7; `PDF_IMPORT_HARDENING.md` §5; BLK-009, BLK-012; CLAUDE.md "PDF", "Schemas", archive-reader gate
- facts: Annex (inventory, measurements and experiments of 2026-10-17)
- status: validated by the owner 2026-10-18 with conditions (§A.6). R4.1 may be prepared once the plan branch is merged, the Safari fix has merged and `feature/rust-r4-pdf-core` is cut from the updated develop.
- not in scope: TTF fonts, `scope_disclaimer`, the planned collection caps, opening the import to external users (BDR-040 gate stays open), R5 (pipeline, `packages/anatomy`, `packages/domain`, `documentSha256`), the Safari download fix (separate bugfix), release 0.2.0, any deployment, any visible change on the documented browsers.
# Part A. For the owner
## A.0 Your arbitrations (2026-10-17), applied as written
A1 one feature branch, one final merge, J1 stop once the import is wired. A2 old PDFs behave as before; differences documented; any break presented before it is applied. A3 years 0 to 99 unchanged (printed 19xx). A4 Producer and Creator `Faunosteo`. A5 new tracing goldens in `goldens/r4/`, frozen goldens untouched. A6 zero render difference; any difference explained, measured, submitted. A7 existing import message; timeout, worker crash and read error told apart technically; 20 s is a hypothesis to measure. A8 rescue copies through the import worker. A9 Firefox and WebKit for Playwright; real Safari still required; module workers vs the Firefox 102 floor: options, policy unchanged unless you decide. A10 `pnpm report:compare` kept. A11 out of R4: TTF, `scope_disclaimer`, collection caps; import closed to external users. A12 WASM budget exceeded: stop and options. A13 real anonymised PDFs join the corpus when you provide them.
## A.1 What R4 delivers
The application reads and writes archives with Rust only. An import, PDF or rescue copy, runs in a Web Worker created for it and terminated after the answer, a timeout or a crash: the main instance never parses the file's bytes. The export composes the views in Rust, rasterises them with the existing canvas adapter, and writes the PDF in Rust through an incremental session. Old PDFs read as before; new PDFs render pixel-identically to R3 for the same inputs. `pnpm report:compare` keeps its name on a Rust binary. `packages/pdf` and `pdf-lib` leave the repository, and every TS test case is traced in a ledger.
## A.2 Decisions to take now
| # | Question | Options | Recommendation |
|---|---|---|---|
| OD-1 | Import worker vs the Firefox 102 floor (A9). Fact found by the challenges: today the import already fails below Firefox 113 and Safari 16.4, because every attachment is Flate-compressed and the TS inflater needs `DecompressionStream` (it answers `attachment_stripped` there); the PNG gate fails the same way (`logo_failed`). | B': module worker everywhere, floor line unchanged, DEPLOY.md states "import needs Firefox 114 or later"; Firefox 113 is the only version that imports today and would not (it would show `error_core_unavailable`), Safari 16.0 to 16.3 and every logo gain. A: classic worker in the production build, module worker in dev; the import works from the documented floor up (a gain on Firefox 102 to 113), at the cost of a dev/production difference, a static check of the worker chunk and a proof on a Firefox 113 binary. B: raise the floor to Firefox 115 ESR (same code as B', policy change). | B' (one worker type, no policy change, one end-of-life version affected) |
| OD-2 | Export memory design (the brief allows leaving the review's two calls only on evidence) | Two calls hold every PNG and the PDF at once in linear memory: ≈ 0.91 MB per view (118 MB for 120 views). The TS engine today holds every decoded RGB plane until `save()`: ≈ 3.8 MB per view (≈ 0.45 GB for 120 views). An incremental session holds the PDF plus one decode: ≈ 0.37 MB per view + 9 MB (53 MB for 120 views), in the main instance, which keeps that high-water until reload (linear memory never shrinks). A disposable export worker frees it but needs a message protocol and an asset fetched at export time (offline export, which works today, would then need a fallback). | Session in the main instance (§B.4); worker only if a device fails (stop rule) |
| OD-3 | Memory guard for large hostile JSON (the worker bounds the blast radius, not the peak; BLK-012 measured 0.4 to 0.8 GB of linear memory for a 5 MB worst-case copy, so a 16 MiB file can exhaust any phone today and after R4) | (b) a JSON value budget in the existing linear pre-scan (attachment probe and copy), set at 10 × the largest legitimate archive measured at R4.2, refusal with today's messages (`error_no_attachment` as an oversized attachment today, `error_invalid_copy`); (a) a module memory maximum (`--max-memory`, above the largest export need) so a runaway allocation traps instead of the OS killing the tab; (c) an attachment cap below 16 MiB; (d) typed parsing without the intermediate `Value` (changes the R2 reader, gated) | (b) + (a), thresholds confirmed by the R4.2 measurements before R4.3 wires the import; both act on files no Faunosteo build writes |
| OD-4 | One JS side effect cannot be reproduced without a JSON reader of our own: a duplicate key whose overwritten value holds a lone surrogate escape imports today (JSON.stringify dropped it) and R4 refuses it (`error_lone_surrogate`) | accept this break (no Faunosteo build writes duplicate keys); or write a lossless JSON round-trip reader (R2 rejected it for the same reason) | accept |
| OD-5 | Messages (existing keys only) | PDF timeout or crash: « Erreur de lecture du PDF. » (A7; today a reader trap showed « Le moteur de lecture n'a pas pu être chargé. Réessayez l'import. »). Rescue copy timeout or crash: `error_core_unavailable` (the same text, which invites a retry) rather than `error_invalid_copy`, which would call a valid copy unreadable | as stated |
| OD-6 | J1 devices and browsers (computer, iPhone, low-end Android), LAN port of the J1 build | | your list |
| OD-7 | Repository weight of the new fixtures (about 5 MB of PDFs, PNGs and compressed bombs) | | accept |
## A.3 Behaviour that changes, declared
- Producer and Creator: `Faunosteo` (A4).
- Messages: OD-5. A foreign PDF picked while the reading engine cannot start now shows the engine message instead of « Ce PDF n'a pas été généré par Faunosteo » (the scan runs in the worker).
- Old browsers gain: logos are drawn without `DecompressionStream` (Firefox 102 to 112, Safari 16.0 to 16.3), and the import works there too (Safari 16.0 to 16.3 in every option, Firefox 102 to 112 under option A only). Visible only on those versions.
- Attachment bytes: the report inside the attachment is written in contract order (D-R11), also when the editor reordered the store object (next appointment set, practitioner edited): values identical, N-1 proof.
- OD-3 and OD-4 refusals, on hostile files only.
- Declared at R3 (RUST.md §9.4), now on the PDF path, no interface reaches it: a foreign archive whose snapshot SVG or branding SVG the R3 reader refuses gets `snapshot_invalid` or `logo_failed` where the TS sanitised and drew.
- `report:compare` prints closed wording where the TS printed a ZodError message, kept a lone surrogate or read a version as `Infinity`.
- Kept as is (A2): invalid UTF-8 becomes U+FFFD (Rust decoder measured identical to TextDecoder on 200,015 byte strings), one BOM stripped, an overflowing number becomes `null`, years 0 to 99 print 19xx.
## A.4 Checkpoints and stop rules
- Checkpoints: (1) this plan; once validated, the plan branch merges, the separate Safari download fix lands, then the feature branch is cut (one develop merge into the feature branch allowed later only with your OK); (2) J1 after R4.3; (3) the final acceptance after R4.9, before any merge.
- J1, on the production build behind the DEPLOY CSP, on your devices: old PDFs (v2 MVP, v3 Step 5, Step 6 and R3 envelopes), the reference PDFs, a hostile folder with the expected message per file, rescue copies (valid, BOM, invalid UTF-8, oversized, refused), an import while the engine is unavailable and after its recoveries, an import interrupted by leaving Home, memory and time readings per device, and the TS export of the large report L on the phones (baseline for OD-2).
- Final acceptance: FR and EN exports of the three reference reports and of a new bilan on computer and phone; each viewer (Chrome, Firefox, Acrobat, Preview or Files, Android) opened once: pages, attachment listed, properties (Producer Faunosteo), footer links; a side-by-side R3 vs R4 page per report, passing when the differences stay within an R3 vs R3 run on the same device (outside private browsing); 400 % zoom and one print as quick confirmations; R4 PDFs imported into the R3 build run side by side; R4 PDFs re-imported (same bilan); engine unavailable during an import and an export; an offline export.
- I stop and come back to you when: the module exceeds 600 KB; any reader or differential difference outside A.3 appears; any §B.2.3 "not acceptable" difference appears; a visible change looks necessary; an export of L fails on a test device; a hostile class breaks its memory budget; a browser proof fails; a gated reader would need a change (`import_archive`, `read_archive_document`, `rebase_report_on_sheet`, `pdf::read`, `json_js`).
## A.5 Your actions
WebKit on this machine: `sudo apt-get install libevent-2.1-7t64 libmanette-0.2-0` (Firefox 157 and WebKit 27.2 for Playwright are downloaded; Firefox runs headless with workers and wasm). The go for the Safari download fix. Real PDFs, if any (§B.5.2).
## A.6 Owner validation (2026-10-18)
OD-1 to OD-7 approved as recommended in A.2 (BDR-057), with these conditions, binding on the slices:
- OD-1: module workers, no second implementation for old versions. The import's support per browser is documented apart from the application's support, from real capability checks (P-W1, J1).
- OD-2: incremental export with bounded memory, cleanup on error and cancellation, offline export kept; release proven at R4.6 on success, error, cancellation and recovery.
- OD-3 (conditional): R4.2 sets the resource budgets from reproducible measurements covering upstream allocations (file buffer, inflation, decoded text, value tree), wasm linear memory, JavaScript objects (transfers, result parse), decoded images and the browser's peak (content-process RSS). If a budget cannot be shown or the preventive caps are insufficient: stop before R4.3 wires the import and present the results. A resource error never alters the original PDF, the bilan or the archives.
- OD-4: the overwritten-duplicate lone-surrogate case is refused; no JSON reader of our own; the source file stays intact, nothing is dropped silently.
- OD-5: messages as proposed; the outcome kinds keep technical errors, resource exhaustion and invalid files apart.
- OD-6: the J1 matrix of A.4 exactly; a device or browser not actually run is reported as not run, never as validated.
- OD-7: about 5 MB of fixtures; no real professional or confidential data in git (B.5.2).
- The A.3 differences stay under the oracles and are reported explicitly at each checkpoint; no other silent difference.
- The harness's 4 GiB RSS watchdog is not a guaranteed memory limit: every result that relies on it says so.
- Proofs owed in the slices, never assumed: png crate tolerance on historical files (R4.5, O6), loading the module in the worker per engine (R4.3), memory on hostile files (R4.2, R4.3, J1), incremental export without image accumulation (R4.6), v2/v3 compatibility (R4.2, R4.5), visual rendering (R4.5, final acceptance), import and export on the J1 browsers (J1, final acceptance), data kept when the engine fails (R4.3, R4.6).
- Goldens stay references, never regenerated to hide a regression; the TS engine is deleted only after parity is proven and every consumer has switched (R4.8).
- Checkpoint reports give concrete results, not plan repetition, and list the functional and graphical validations available. Manual priorities: FR and EN export, anatomical views and markers, a v3 import, real historical v2 PDFs, attachments and kept data, wrong and large files, the targeted browsers and phones.
- Order: R3 closed (checked 2026-10-18: merge 8df964b on develop, branch deleted locally and on origin); this plan merged; the Safari fix on a short branch, tested, merged after the owner's validation; `feature/rust-r4-pdf-core` from the updated develop. WebKit packages installed by the owner, then workers, wasm, imports, exports and memory protections checked on WebKit; WebKit results never replace a manual iPhone run. LAN DEV access kept. Excluded: R5, any deployment or production change, release 0.2.0, any graphical redesign.
# Part B. The plan
## B.1 Architecture and contracts
### B.1.1 Modules (`crates/core`, features `pdf-read`, `pdf-write`, `cli`; the wasm facade enables both pdf features, the worker crate neither)
```
src/pdf/
read/{header,scan,strings,inflate,probe,stamp}.rs bytes → Attachment | ReadKind (B.1.2)
json_js.rs JS-path side effects: overflow → null rewrite, value budget (OD-3), probe text
import.rs import_pdf(sheet, bytes) = read → text → session::import_archive (unchanged)
write/
input.rs ExportInput checks (branding and labels schemas, assert_snapshot, read_svg per
asset, sheet ref match, caps), envelope as JSON.stringify(_, null, 2) + js_number
session.rs ExportSession state machine (B.1.4)
views.rs raster requests: compose_highlight (R3) per (observation, view), raster_size_of
layout/{observation,conclusion,header,footer}.rs → DrawLog
text.rs, afm/ (3 fonts), dates.rs, png.rs (branding gate, decode), content.rs (emitter,
number_to_string), serialize.rs (pdf-writer), self_check.rs (B.1.3)
from_envelope.rs exportFromEnvelope, cargo-tested, not on the facade
src/bin/report_compare.rs feature cli, the only file allowed std::fs
```
New crates: `pdf-writer` (MIT or Apache-2.0), `miniz_oxide` (inflate and deflate, already locked through `image`; one version for the core), `png` (0.18.1, already locked); `lopdf` as a dev-dependency only. No new npm dependency.
### B.1.2 Reader (identical to scan.ts; every rule pinned by O7 to O9)
- File ≤ 50 MiB and `%PDF-` within the first 1,024 bytes, else `invalid_pdf`.
- At most 32 `/Type /EmbeddedFile` dictionaries, each bounded to 4,096 bytes; object header from a 48-byte window; `stream` then `\r\n` or `\n`; a direct `/Length` when it lands on `endstream`, else measured up to the first `endstream` within 16 MiB + 16 (one trailing `\n` then one `\r` dropped); `/FlateDecode` alone or first in an array, else raw.
- JS regex semantics reproduced explicitly: `\s` in the header, `/Length`, `/Filter`, `/EF` and `/F` patterns matches 0x0B and 0xA0 but not NUL, while `isWhitespace` matches NUL and neither of those; in the string token `.` excludes CR and LF; the `/EF` removal is lazy up to the first `>>`; a candidate whose stored length exceeds the remaining budget ends the search (`break`), it is not skipped.
- Names from Filespec dictionaries in clear (`/F`, else `/UF`), `osteo-report*` first (stable), then data offset. One 16 MiB budget shared by the candidates; a cancelled inflation is not charged.
- A candidate opens on `{` after an optional BOM and JSON whitespace and nests at most 64 levels (raw bytes, strings skipped, a backslash skips one byte); the same pass counts JSON values (OD-3 budget). Then lossy decode (`from_utf8_lossy` after one BOM), the overflow → null rewrite (number tokens that overflow f64, as JSON.stringify wrote ±Infinity), and the probe: a copy of the text with lone surrogate escapes neutralised goes through R2's `parse_json` (JS duplicate-key semantics) and must be an object with a numeric `version` or `envelopeVersion`. The accepted text, with its real escapes, goes to `import_archive`, which refuses a surviving lone surrogate as today.
- No candidate: `attachment_stripped` when a `/Keywords` string (≤ 32 occurrences, 4,096-byte window, hex, or literal with the same limited unescape, UTF-16BE with BOM else Latin-1) contains `faunosteo-archive`, else `no_attachment`.
- Inflation: zlib framing, verdicts of `DecompressionStream('deflate')` as recorded in Node, Chromium and Firefox (O9); where engines disagree, Node's verdict is pinned and the others are listed. Output capped by the remaining budget, cancelled beyond it.
### B.1.3 Writer
- Input `ExportInput { report, sheetSnapshot, branding, labels, locale, exportedAt }` (ts-rs; `exportedAt` an ISO string from the caller; labels from `apps/app/src/pdf/labels.ts`, moved verbatim from `packages/pdf/src/i18n`, same key order: the review's II.2 kept them with the engine, the app keeps them as data like the other dictionaries).
- Errors before any page, today's kinds: `branding_invalid`, `snapshot_invalid`, `snapshot_too_large`, `sheet_mismatch`, `too_many_pages`. Warnings unchanged: `view_raster_failed { observationId, viewId }`, `logo_failed { slot }`.
- Layout → `DrawLog` (per page, in call order: text, image, line, rectangle, link, every argument at full precision) → `content.rs` emits pdf-lib's operator sequences with `numberToString` reproduced, quirks included (the exponent branches multiply or divide) → `serialize.rs` with pdf-writer: catalog (Pages, Names/EmbeddedFiles, AF), A4 pages, three Type1 fonts with WinAnsiEncoding, image XObjects (DeviceRGB 8 bits, DeviceGray SMask with `Decode [0 1]` when an alpha < 255), Link annotations (`Border [0 0 0]`, URI action), Info (Producer and Creator `Faunosteo`, the rest as today in pdf-lib's string forms: UTF-16BE hex with BOM, dates literal), the attachment objects as today, classic xref, no object stream, no `/ID`. The output buffer is pre-sized; each image object is written as soon as its PNG is decoded, and the PNG and planes are dropped.
- Text rules: width = `total * (size / 1000)` with `total` the sum of AFM widths (`|| 250`, so a zero width counts 250) plus KPX kerning; `safeText` with the Cc, Cf, Zl and Zp sets frozen from V8 (O4); `wrapLines` on JS `\s`; JS `toUpperCase`; `Math.round` half up; `rasterSizeOf` parsing the viewBox with JS `Number()` semantics (hex, `Infinity`).
- PNG: the gate (`pngIssue` port) applies to the base64 branding PNGs only, as today; view rasters and the SVG-logo raster are decoded with UPNG's acceptance rules (no CRC check, ancillary chunks ignored); decode under limits (a gated 4096² logo is 64 MiB of RGBA), RGBA8 like `UPNG.toRGBA8`, alpha plane kept only when an alpha < 255.
- Self-check: `finish()` re-reads its own output with the R4 reader and compares the attachment with the envelope it wrote; a mismatch fails the export (`self_check_failed`, today's export alert). It costs one scan and one 55 KB inflation.
### B.1.4 Facade (`crates/wasm`)
- `SheetHandle.importPdf(bytes: Uint8Array) → string`: `{ ok: true, value: ArchiveImport } | { ok: false, kind, detail }`, kinds `invalid_pdf`, `no_attachment`, `attachment_stripped`, `incompatible_version`, `lone_surrogate`, `invalid`, `internal`. The rescue copy keeps `SheetHandle.call('draft.restore', …)` plus the OD-3 value budget.
- `ExportSession` (wasm-bindgen struct), every call made through `CoreRuntime.invoke` (a trap poisons and recovers as any core call), bound to the runtime generation (refused with `core_unavailable` after a recovery, like `SheetSession` handles), `free()` in the driver's `finally` and on EditorRoute unmount.
| State | Call | Effect |
|---|---|---|
| none | `new(inputJson)` | validates; throws `"<kind>: <detail>"` with the B.1.3 error kinds; → `branding` |
| `branding` | `next()` | requests for the SVG logos (`logo:<slot>`; PNG logos need none); none → first observation |
| `observation k` | `next()` | the views of observation k (`view:<observationId>:<viewId>`), main view first as today |
| any batch | `addRaster(key, png)` / `rasterFailed(key)` | key of the current batch, answered once; else closed kinds `unknown_key`, `duplicate_key` (never a trap). A decode failure or `rasterFailed` records the warning for that key. When every key is answered, the logos are embedded or the page is laid out and written |
| any | `next()` with unanswered keys, `finish()` before `done` | closed kind `out_of_order` |
| `done` | `finish() → Uint8Array` | self-check, then the PDF; `warnings()` readable afterwards |
- The driver keeps the TS ordering: `rasterFailed` is called as each raster rejects (rejection order, as the TS recorded them under `Promise.all`), `addRaster` in view order once the batch has settled (embedding order), so the warning list and the alert read the same.
- ts-rs types committed under `packages/core-wasm/types`: `ExportInput`, `RasterRequest`, `ExportStep`, `ExportWarning`, `PdfImportKind`.
### B.1.5 Import worker (`apps/app/src/core/worker/`, messages tagged `v: 1`)
1. The main thread refuses up front when its runtime is `stopped` (today's text). It creates the worker in a try/catch (`SecurityError` is synchronous), installs `onmessage`, `onerror` and `onmessageerror` first, and arms a start timer.
2. The worker entry installs its listener before any await, wraps its whole life in one try/catch, and adds `self.onunhandledrejection` as a backstop: every throwable becomes `{ type: 'failed', phase: 'start' | 'task', kind }` (`trap` for `RuntimeError`, `RangeError` and `InternalError` stack overflows, `read` for a file the browser cannot read, `alloc`, `sheet`, `other`). The glue is imported statically and bundled into the worker chunk (no `import()`, no recovery logic). The module is the compiled `WebAssembly.Module` posted by the main thread when its runtime holds one (structured clone; proven per engine), else fetched and compiled from the same asset URL. It instantiates once and posts `ready`.
3. On `ready`, the main thread clears the start timer, posts `{ v: 1, task, file, sheet, limits }` (the `File` itself, never read on the main thread; the bundle text the main runtime builds, about 522 KB) and arms the task timer (`IMPORT_TIMEOUT_MS`, 20 s hypothesis), paused while the page is hidden.
4. The worker re-checks `file.size` (50 MiB PDF, 16 MiB copy), reads `file.arrayBuffer()` once, builds a `SheetHandle`, runs `importPdf`, or the strict TextDecoder then `draft.restore`, and posts `{ type: 'result', out, diag: { ms, linearBytes } }` (`linearBytes` from the instance's exported `memory`; printed in DEV only, never sent anywhere).
5. The first settlement wins; anything after it is ignored. `terminate()` in every case, timers cleared, references dropped. Classification: failure before `ready` or start timeout → `worker_unavailable`; `trap` → `crashed`; task timer → `timeout`; `read` keeps today's mapping (pinned by a route test).
6. One module-level controller runs one import at a time across mounts; leaving Home cancels it (terminate, result dropped), and a result is dropped if the store's report changed since the pick.
7. When the main runtime finishes loading (editor), the worker script is prefetched so that a later offline import can start, as an offline import works today once the editor has loaded the engine.
8. vitest (happy-dom has no `Worker`) runs the worker entry in-process through the client's spawn seam; the real worker runs in the browser harness and in the per-slice browser proof (B.7).
9. The main instance receives the core's canonical output only; it loads its index after acceptance, for `hydrateImport`, as today.
### B.1.6 Export driver
The main thread computes `archive.snapshot` (the sheet handle, as today), builds `ExportInput` (branding from `loadBranding()`, labels from `labels.ts`, `new Date()`), loops `next()`, rasterises each batch with `browserRasterizer` under `Promise.all` as today, answers with `addRaster` or `rasterFailed`, then `finish()`, download, the warnings alert unchanged. Any thrown error keeps today's alert (`editor.export_failed`, or the stopped text). A raster that never settles hangs the export as it does today (residual, unchanged).
### B.1.7 `report-compare`
A `crates/core` binary behind `cli`, same arguments, output lines and exit codes as the TS CLI (O10, LRN-044 escaping), except the lines listed in A.3. Root script `report:compare` → `cargo run --release --locked -q -p faunosteo-core --features cli --bin report-compare --` (development machine toolchain; the first run compiles).
### B.1.8 Import outcomes and messages (existing keys; today's mapping kept)
Order: main pre-checks (routing on the first KiB, sizes), then the worker's reading (its messages come first, as the scan's did), then the main index for `hydrateImport`, then the held-session checks.
| Outcome | Message |
|---|---|
| PDF > 50 MiB, no `%PDF-` | `home.import.error_invalid_pdf` |
| `no_attachment` (incl. an OD-3 refusal) | `error_no_attachment` |
| `attachment_stripped` | `error_attachment_stripped` |
| `incompatible_version` | `error_incompatible_version` |
| `lone_surrogate` | `error_lone_surrogate` |
| PDF `invalid` (rebase refused) | `error_generic` (today) |
| PDF non-trap `internal` or `core_unavailable` from the worker's core | `error_core_unavailable` (today) |
| PDF `crashed` or `timeout` | `error_generic` (A7, OD-5) |
| copy > 16 MiB, invalid UTF-8, `draft.restore` kinds `invalid`, `unsupported_version`, `lone_surrogate`, OD-3 refusal | `error_invalid_copy` (today) |
| copy other kinds (`rebase_failed`, `invalid_shape`, non-trap `internal`) | `error_core_unavailable` (today) |
| copy `crashed` or `timeout` | `error_core_unavailable` (OD-5) |
| `worker_unavailable`, no bundled sheet, main index failure | `error_core_unavailable` |
| main runtime stopped | `core.stopped` or `core.stopped_unsaved` |
| held session | `session.held_blocked*` |
The technical kind stays in the outcome and in the DEV console.
## B.2 PDF compatibility
### B.2.1 Behaviours preserved (pinned by O7 and O8 rows)
H1 bare v2 MVP PDFs with object streams: migrated. H2 bare v3 from Step 5: read as is, rebased when the sheet differs. H3 envelopes from Step 6 (pre-R2 key order, O3) and from R2 and R3 (O2): layered reading, report kept when the snapshot is rejected. H4 stamped PDFs with object streams: a stripped attachment reads `no_attachment`. H5 several embedded files: `osteo-report*` first, then data order. H6 indirect, wrong or missing `/Length`, `\r\n` after `stream`, `/Type/EmbeddedFile` without a space, hex and literal names, unfiltered streams. H7 caps: 50 MiB, 32 candidates, 4 KiB dictionaries, 16 MiB shared budget, depth 64. H8 invalid UTF-8 → U+FFFD, one BOM stripped. H9 JSON: duplicate keys keep the last value at the first position, overflow → `null`, lone surrogate refused (R2), numbers as f64, integer-like keys (benign, typed outputs). H10 encrypted PDF: `no_attachment`. H11 every B.1.8 message. H12 rescue copy: BOM accepted, strict UTF-8, ≤ 16 MiB, `draft.restore`, `editor.draft_rebased`.
### B.2.2 Readers that must read R4 PDFs (N-1)
The frozen TS scanner (O11) and the N-1 Zod copy, which stand for the R3 build and release 0.2.0 (Annex), read every R4 fixture PDF and app-path export; an R4 PDF with its EmbeddedFile stream removed must answer `attachment_stripped` through O11, and a byte test pins the `/Keywords` form. The R3 build, run side by side, reads them at the final acceptance. The live site (pre-Step 6) reads no envelope today. DEPLOY.md's rollback note says that R3 and 0.2.0 read R4 PDFs.
### B.2.3 Difference classes (R3 build vs R4 build, same inputs)
Acceptable, each checked by a test:
- B1 Flate bytes of every stream: decompressed bytes compared.
- B2 object numbers, order, offsets, header binary comment, xref and trailer layout (both classic xref).
- B3 resource names: pdf-lib registers a new name per draw call; streams are compared after resolving each name through `/Resources` to its object.
- B4 string forms with the same decoded value where pdf-writer chooses (the link URI); Info, `/UF`, `/Desc` and the names key keep the UTF-16BE hex form.
- B5 dictionary numbers nothing reads at `f32` precision (link `/Rect`, under 0.0001 pt) if pdf-writer has no exact primitive; MediaBox checked to print the same.
- B6 key order, whitespace, structural keys without effect (listed when found).
Decided: Producer and Creator (A4); the attachment's report in contract order (D-R11, A.3). Every other Info value identical.
Not acceptable without the owner: a pixel difference in the poppler render (150 dpi, every page); a content-stream difference after B3; a decoded image difference (planes, size, depth, colour space, SMask); a draw-log difference; links, page count, size or order; the attachment's filename, subtype, Params, Desc, AFRelationship, names tree, `/AF`, or JSON bytes beyond the D-R11 order; an import outcome difference on O2, O3, O7, O8, the hostile set or real PDFs, outside A.3.
## B.3 Import and memory
- Isolation: untrusted bytes are read only inside the worker created for that import. This closes the read residual of RUST.md §8.8 and the trapping-copy residual of BLK-012 (a trap no longer spends a main recovery). It does not close the accepted-content residual: an accepted report and envelope come back to the main thread and are parsed there again by later actions, export and reload; that stays until the collection caps (PDF_IMPORT_HARDENING §5) and is measured (class "largest accepted file": transfer, hydrate, one list action, export, reload; main linear memory and RSS).
- Transfer: the `File` is posted, read once in the worker, copied once into linear memory; the sheet travels per import as the bundle text; the result comes back as one JSON string; each step's cost measured.
- Time: a start timer until `ready` (worker_unavailable) and the task timer. Rule for the task timer: ≥ 10 × the slowest legitimate import (an L-size archive and copy) on the slowest device, ≥ 2 × the slowest hostile case that completes; you set the value at J1 if the rule moves it away from 20 s. CPU throttling of worker threads by CDP is unverified: the harness records unthrottled numbers and the throttle actually applied.
- Destruction: `terminate()` in every case; the harness checks the content process comes back within 10 MiB of its pre-import level after a forced GC (Chromium CDP), and Firefox `about:memory` at J1.
- Out of memory: a worker shares the tab's content process, and iOS kills the whole tab beyond its limit. Measured classes, in Node at R4.2 then in the browsers: a 16 MiB token-dense attachment, a 16 MiB rescue copy through `draft.restore` (its input nests the copy as a JSON string, one extra copy), the 50 MiB file, the 16 MiB inflation, 32 candidates. Budget W4. With BLK-012's 80 to 160 × ratio the first two break it today: OD-3 brings the guard before R4.3.
- Rescue copy: same worker, timers and termination; strict TextDecoder in the worker; routing on the first KiB stays on the main thread.
## B.4 Export memory: PNG accumulation
| Design (V rasterised views) | Peak | Kept after the export |
|---|---|---|
| TS today: every RGB plane from `embedPng` to `save()`, then the PDF | ≈ 3.4 V + 0.37 V MB + PNG transients | nothing (garbage-collected) |
| Two calls (review sketch) | ΣPNG + PDF + one decode ≈ 0.91 V + 9 MB | the same, by the main instance |
| Session in the main instance (OD-2) | PDF + one decode ≈ 0.37 V + 9 MB | the same high-water, until reload |
| Session in a disposable worker | as above, inside the worker | nothing |
Per view: PNG ≈ 0.54 MB (resvg; browser PNGs measured at R4.1), decoded RGBA + RGB + alpha ≈ 9 MB transient, image stream ≈ 0.37 MB (our own deflate of the RGB plane, independent of the browser). The JS side adds the PDF twice at the end (`Uint8Array`, then the `Blob`). With the draft sheet's two views, the cap is 500 × 2 = 1,000 views.
| Report | V | TS today | Two calls | Session |
|---|---|---|---|---|
| demo | 7 | ≈ 27 MB | ≈ 15 MB | ≈ 12 MB |
| L (60 obs × 2) | 120 | ≈ 0.45 GB | ≈ 118 MB | ≈ 53 MB |
| CAP (500 × 2) | 1,000 | ≈ 3.8 GB (fails) | ≈ 0.92 GB | ≈ 0.38 GB |
Measurement (R4.1 baseline, R4.6 for R4): harness in Chromium and Firefox (WebKit once it starts), linear memory after each session step, content-process RSS sampled every 50 ms from `/proc`, JS heap from CDP; reports demo, L and CAP (O13). The harness enforces its own ceiling (it closes the browser when the browser's processes exceed 4 GiB RSS) so that the shared development host never reaches the kernel OOM killer; a run stopped by the ceiling is recorded as such. Phones: TS L at J1, R4 L after R4.6 (your check), before the gates.
Strategies if a device fails L with the session: S2 the disposable export worker (with the main-instance session as its offline fallback), S3 chunked output (image streams handed out as Blob parts), S4 visible or behavioural measures (raster resolution, a smaller cap) never without you.
## B.5 Fixtures and oracles
### B.5.1 Frozen with the TS code at R4.1, before any Rust (generators behind `MAKE_R4_ORACLES=1`; never regenerated without the owner)
| Id | Content | Location (planned) | Used by |
|---|---|---|---|
| O1 | draw log, 3 reports × fr/en × logos/nologos = 12: every drawText, drawImage, drawLine, drawRectangle and link call in order, all arguments, full precision (step6 fixed rasterisers, FIXED_EXPORTED_AT) | `apps/app/tests/fixtures/goldens/r4/draw.*.json` | R4.4 |
| O2 | the 12 matching R3-build PDFs; one real-raster PDF (v2full fr logos) with its view PNGs and SVG-logo PNG; one PDF exported through the store path (next appointment set, practitioner edited) | `apps/app/tests/fixtures/pdf/r3/` | R4.2, R4.5, N-1 |
| O3 | pre-R2 envelope PDFs: the three frozen `goldens/r2/envelope.*.json` attached byte for byte by pdf-lib 1.17.1 | `apps/app/tests/fixtures/pdf/step6/` | H3, N-1 |
| O4 | text and numbers: widths (strings × sizes × 3 fonts, from the pdf-lib metrics, which also generate the Rust AFM tables once, APAFML notice committed), `wrapLines`, `safeText` over every code point class, `toUpperCase` differences over all code points, JS `\s`, `Math.round`, `numberToString` (random, edge and tiny-exponent values such as 1e-13), `rasterSizeOf` viewBox parsing | `crates/core/tests/oracles/r4/text.json`, `afm.json` | R4.4 |
| O5 | `formatDate` fr and en over years 0000, 0001, 0050, 0099, 0100, 0999, 1000, 1900, 1904, 1999, 2000, 2024, 2026, 9999 × months 00 to 13 × days 00 to 32, plus non-matching strings | `oracles/r4/dates.json` | R4.4 |
| O6 | PNG: gate verdicts (security-suite PNGs, brand logos, variants: palette, palette + tRNS, grey, grey + alpha, 16-bit, RGB, RGBA); UPNG decode of accepted and raster-path PNGs incl. bad-CRC and malformed-ancillary variants: sha256 of the RGB and alpha planes or the failure | `oracles/r4/png.json` + PNGs | R4.5 |
| O7 | reader outcomes for every input of scan, inflate, read and the reader part of security, plus rows for the B.1.2 regex semantics: kind, chosen candidate, digests. Inputs committed as bytes, the zlib bombs included (compressed, about 65 KB for 64 MiB) and the inputs cut from a demo export; generators only for uncompressed fillers | `oracles/r4/read.json`, `fixtures/pdf/r4/read/` | R4.2 |
| O8 | differential corpus: UTF-8 classes, BOM, double BOM, overflowing numbers (in `version` and in content, in a duplicate), lone surrogate (probe, content, overwritten duplicate: OD-4), duplicate keys incl. `version`, integers beyond 2^53 and u64, `-0`, `__proto__`, integer-like keys, depth 64 and 65, a first candidate only JSON.parse accepts, value-budget limits (OD-3); outcome of the full R3 path (TS scanner, JSON.parse and stringify, core `archive.import` in wasm) | `fixtures/pdf/r4/tolerance/`, `oracles/r4/tolerance.json` | R4.2 (a difference outside A.3 is a stop) |
| O9 | inflate: valid, empty, truncated, bad Adler-32, trailing bytes, raw deflate without zlib header, preset dictionary, exact cap, cap + 1: `DecompressionStream` verdict and digest in Node, Chromium and Firefox | `oracles/r4/inflate.json` | R4.2 |
| O10 | `report:compare` stdout and exit code on every fixture PDF and the 11 scenarios | `oracles/r4/compare/` | R4.7 |
| O11 | frozen TS scanner: verbatim copy of R3's `attachment/{scan,inflate,read}.ts` and their errors, never edited (the permanent N-1 PDF reader) | `packages/core-wasm/tests/n-1/scanner/` | N-1 |
| O12 | TS baseline in Chromium and Firefox with the real `browserRasterizer`: PNG bytes per view, export time, RSS peak and after, JS heap, PDF size (demo, L, CAP); TS import time and memory on O2 and the hostile set | RUST.md §10 (draft) | B.3, B.4, B.8 |
| O13 | synthetic reports L (60 × 2) and CAP (500 × 2) built from the demo | `apps/app/tests/fixtures/r4/reports/` | O12, R4.6 |
The step6, r2 and r3 goldens and the R3 oracles stay untouched: `git diff --stat` on them is empty at every slice. (Oracle ids renumbered in rev 2; references below use these.)
### B.5.2 Real PDFs (A13)
Kept outside the worktree (`$FAUNOSTEO_FIELD_CORPUS`, a test refuses a path inside it), read by an opt-in test; only a table without personal data is committed (sha256, producing build when known, expected outcome, observation count); the oracle generators refuse to run while the variable is set. A file enters git only after you review its anonymised form: attachment strings, page text, Info (Title holds the animal name, Author the practitioner), Filespec and file names replaced, streams re-encoded with corrected `/Length`.
## B.6 Test traceability
`crates/core/tests/pdf/LEDGER.tsv`: one row per TS case at the freeze commit (TS file, full case title, disposition `ported` / `replaced` / `kept` / `deleted`, target cargo `file::test` or vitest `file > title`, oracle id, note). Scope, built from vitest's JSON reporter at R4.1: the 140 engine cases; the PDF app suites (pdf.goldens 13, pdf.roundtrip 16, pdf.import 5, archive.envelopes 3, n-1.reader 6, pdf.export.app 2, migration.leaves 2, pdf.browserRasterizer 2, scripts.compare 11); the suites that mock `@/pdf/*` and are rewritten at R4.3 or R4.6 (routes.HomeRoute.archive 5, routes.HomeRoute.import 11, routes.HomeRoute.rescueCopy 13, routes.EditorRoute.export 5, routes.coreStopped 15, state.coreFailures 5). A census check fails when a frozen case has no row, a `ported` target is missing from `cargo test -- --list` or the vitest list, or the counts do not reconcile; the verifier runs it. Rust test files keep a header naming their TS source.
## B.7 Slices
One branch, `feature/rust-r4-pdf-core`, cut from develop after this plan and the Safari fix have merged. Every slice ends green on `pnpm rust:check`, `pnpm wasm:build` and `pnpm check`; from R4.3 on, also on the browser proof (the production image behind the DEPLOY CSP, an import of one reference PDF in Chromium and Firefox, WebKit once it starts). Proofs recorded in the TODO and RUST.md §10.
| Slice | Deliverable | Proof |
|---|---|---|
| R4.1 Freeze | O1 to O13, ledger, browser harness (`scripts/browser/`, Playwright kept outside the repository) | generators committed, frozen goldens untouched, suites green, baseline table; no Rust |
| R4.2 Reader | `pdf::read`, `json_js`, `pdf::import`, `SheetHandle.importPdf`; reader suites in cargo on O7 and O9; O8 differential; hostile corpus and OD-3 classes through the wasm build in Node (fresh instance per case, time, linear memory) | 0 oracle difference, 0 differential difference outside A.3, OD-3 thresholds measured and confirmed with you, W1 |
| R4.3 Import worker, rescue copy | B.1.5; HomeRoute on the controller (routing and pre-checks unchanged); OD-1 applied; client tests per throwable and phase, settle-once, result after timeout, error after result, unmount, second pick, main runtime untouched; message test over O2, O3, O8 and the hostile set; 612 leaves through the worker (export still TS); CSP proof with and without `'wasm-unsafe-eval'`; time and memory | B.1.8 messages on every file, W2, W4, W5 |
| J1 | A.4; results in PDF_IMPORT_HARDENING §5 (gate still open) | your OK, timeout value, OD-1 confirmed on real browsers |
| R4.4 Layout | text, AFM, dates, upper-casing, `safeText`, `wrapLines`, the four layouts → DrawLog | O1 (12) exact at full precision, step6 text and images (24) exact, O4 and O5 exact |
| R4.5 Serialiser | emitter, pdf-writer, PNG gate and decode, links, Info, attachment, self-check, `from_envelope`; export-side security, size, reexport and text suites in cargo | against O2: streams equal after B3, image planes equal, links (lopdf) and step6 links (12) equal, Info equal but Producer and Creator, attachment bytes equal (the store-path PDF differs by D-R11 order only); `qpdf --check` clean; `pdfdetach -list` shows `osteo-report.json`; poppler 150 dpi diff 0 px; O11 and the N-1 copy read every R4 PDF, the stripped PDF answers `attachment_stripped`; E2; digests of R4 outputs in `goldens/r4/pdf.*.sha256` (wasm output = native output) |
| R4.6 App export | session driver, `labels.ts`, `export.ts` on the session; alerts unchanged | app suites; app-path bytes = native digests; step6 views via the app path; browser rasters of the Rust- and TS-composed views pixel-identical in Chromium and Firefox (WebKit once it starts); E3, E4; your phone check of L; 612 leaves exported and re-imported on Rust |
| R4.7 report-compare | Rust binary, `pnpm report:compare` unchanged | O10 and the 11 cases in cargo, A.3 lines declared |
| R4.8 Deletions, docs | `packages/pdf` (with the R3 oracle generators; the oracle files stay), `@faunosteo/pdf` and `pdf-lib` in apps/app, the TS CLI, the pdf-lib-based tests per the ledger; N-1 test on O11; RUST.md §10, PDF-FORMAT, PDF_IMPORT_HARDENING §5, DEPLOY (rollback, worker CSP note, floor line per OD-1), CHANGELOG, CLAUDE.md (map, PDF section, gated readers `pdf::read` and `json_js`), TEST_STRATEGY, WORKSPACE, packages/README, fixtures README | `pnpm check:all` green, ledger census green, D1 |
| R4.9 Gates, acceptance | verify contract, fresh verifier, fresh security audit, then your final acceptance (A.4) | verifier CONFORME, security PASS, your explicit merge signal |
## B.8 Budgets (measured, recorded in RUST.md §10)
| Id | Budget |
|---|---|
| W1 | served module ≤ 600 KB gzip -9, reported at 550 KB, stop above 600 (A12); estimated +100 to 150 KB |
| W2 | worker start + an L-size legitimate import ≤ 1 s on the development machine (Chromium); recorded per J1 device |
| W4 | worker linear memory ≤ 256 MiB on every hostile class once OD-3 applies; the tab survives on every device (per device: the tab survives, plus `diag.linearBytes`); content process back within 10 MiB after GC |
| W5 | main-thread long tasks during the worker's reading ≤ 50 ms |
| E2 | PDF size ≤ R3 + 5 %; stored attachment < 250 KB (demo with logos) |
| E3 | export time ≤ 1.2 × the TS baseline (demo, L) in Chromium |
| E4 | L completes on the development machine and on your phone; CAP completes on the development machine within the harness ceiling; R4 never fails where the TS completes |
| D1 | no `pdf-lib` or `@pdf-lib/*` left in the lockfile; no `@xmldom/xmldom` in apps/app's closure (kept by `packages/anatomy` until R5, as the review's criterion reads it for the apps/app importer) |
Render (B.2.3), timeout (B.3) and traceability (B.6) are rules, defined where they live.
## B.9 Browser compatibility
- Floor documented for the keyword: Chrome 97, Firefox 102, Safari 16; the bundle's syntax target is Firefox 104 (Vite 7 default), and the import works today only from Firefox 113 and Safari 16.4 (`DecompressionStream`). The DEPLOY.md wording changes only per your OD-1 decision.
- Module workers: Chrome 80, Firefox 114, Safari 15; `import()` inside workers ships with them. The worker never uses `import()` (static glue), so option A stays possible.
- Proof P-W1 at R4.3 (B': Chromium, Firefox 157, WebKit once it starts; A: plus a static check that the production worker chunk holds no ESM syntax and is started without `type: 'module'`, and a run on a Firefox 113 binary in a throwaway, offline, loopback-only profile, checksum verified, failures classified as syntax, worker type or CSP): the built worker runs under the production CSP, receives the compiled module, imports a reference PDF and a copy.
- CSP: the worker is a same-origin hashed file under `/assets/`, allowed by `script-src 'self'`; its response carries the proxy's CSP with `'wasm-unsafe-eval'`; no `blob:` or inline worker; no CSP change (DEPLOY.md gains a note). Without the keyword the import answers `error_core_unavailable`, no fallback.
- Safari: automated once WebKit starts (A.5); real Safari (macOS when available, iOS) at J1 and at the final acceptance; the download fix lands separately before the iPhone acceptance.
- Worker APIs: `Blob.arrayBuffer` (Firefox 69, Safari 14), `WebAssembly.compileStreaming` with the main runtime's fallback, structured clone of `WebAssembly.Module` (proven per engine, fetch otherwise), `TextDecoder`, transfer lists.
## B.10 Risks
| Risk | Mitigation | Detection |
|---|---|---|
| Writer exactness (float order, `Math.round`, kerning, upper-casing, the Cf set, dates, `numberToString` quirks) | port expression by expression; full-precision O1; O4, O5 | O1, B3-normalised streams |
| pdf-writer's `f32` or string forms change a form the N-1 scanner reads | pdf-lib's string forms written explicitly; B5 limited to numbers nothing reads | O11 read-back, stripped PDF, byte test |
| Reader divergence on old or foreign PDFs | O7, O8, real PDFs | stop rule |
| Inflate verdicts differ per engine | O9 in three engines, Node pinned, others listed | R4.2 |
| Worker failures misclassified, late results, races | B.1.5 rules and their tests | R4.3, J1 |
| Memory exhaustion despite the worker | OD-3 before R4.3, W4 classes, accepted-content class | R4.2, harness, J1 |
| Export memory on phones | session, phone checks at J1 and after R4.6 | E4 |
| The measurement itself exhausts the shared host | harness ceiling (4 GiB RSS), no unbounded probe | harness log |
| WASM size | three fonts, features, measured per slice | W1 |
| A test lost in the migration | ledger census over every PDF-touching suite | verifier |
| Canvas noise hides or invents differences in the final comparison | R3 vs R3 run as the pass threshold; automated proofs use frozen PNGs | final acceptance |
| A production-only worker break between R4.3 and R4.9 | browser proof at every slice end | each slice |
| Largest phase of the roadmap | J1, per-slice proofs, stop rules | slice reports |
## B.11 Kept and deleted (consumers named)
- Deleted at R4.8: `packages/pdf/**` (last consumers: app import at R4.3, app export at R4.6, CLI at R4.7, tests per the ledger), `apps/app/scripts/compare-reports.ts` and `compare/*`, `@faunosteo/pdf` and `pdf-lib` in apps/app, `@resvg/resvg-js` and `@pdf-lib/*` with packages/pdf.
- Kept: `browserRasterizer.ts` (DOM adapter), `loadBranding` and `src/assets/brand`, `packages/anatomy/render` and `packages/domain` (pipeline, R5), the frozen R3 oracle files (generators deleted with packages/pdf, never regenerated), the N-1 Zod copy, O11.
- Amendments to the review's VI.2 R4 row, listed: the export is an incremental session, not two calls (OD-2); the render threshold is 0 px (A6) with stream equality; N-1 = O11 + the N-1 Zod copy (R3 and 0.2.0); BLK-009 measurements per engine and per owner device; the rescue copy goes through the worker (A8); Producer and Creator (A4); labels move to the app; `exportFromEnvelope` is cargo-only; the lockfile criterion reads apps/app's importer.
## B.12 Revision 2 log
Folded (main points): worker failure classification with a top-level catch, unhandled rejections and synchronous `SecurityError`; settle-once and listener order; an import controller across mounts and dropped late results; start timer separate from the task timer, paused while hidden; copy timeout and crash on `error_core_unavailable`; message precedence and today's mapping for every kind; the third JS side effect (overwritten duplicate with a lone surrogate, OD-4) and the probe on R2's `parse_json` instead of a new grammar; `DecompressionStream` facts and their per-browser differences; static glue in the worker (no `import()`), compiled module posted by the main thread, worker script prefetched for offline imports; the TS memory row corrected (RGB planes held until `save()`), the 9 MB transient, the cap at 1,000 views for the draft sheet, L and CAP instead of XL and a doubling probe; OD-2 as a decision with the main-instance session under the runtime's poison and generation rules, offline-safe; OD-3 before R4.3 using BLK-012's measured ratio, the copy class and the accepted-content class; phone checks at J1 and after R4.6; the harness ceiling; the D-R11 order of the attachment's report and a store-path fixture; committed zlib bombs; JS regex semantics; PNG gate scope and UPNG acceptance; the stripped-PDF N-1 proof; `report:compare` lines declared; warning order; `rasterSizeOf` parsing; branding SVG through the R3 reader; ledger widened to the mocking suites; VI.2 amendments listed; `exportFromEnvelope` off the facade; AFM tables generated from the oracle that tests them; one poppler pass; the owner part first, facts in the annex, open decisions reduced to real ones; real-PDF anonymisation extended; gated readers extended; the branch cut after the Safari fix.
Not folded, with the reason:
- A throwaway main-thread instance per export (simplicity 1): the wasm-bindgen glue keeps its instance in a module variable and module records are never unloaded, so each throwaway instance would stay in memory until reload (measured at R3, BLK-012: dead instances retained). The finding's conclusion (no export worker by default) is adopted through OD-2.
- A raster timeout in the export (robustness 12): it would turn today's hang into a missing-image warning, a behaviour change; kept as today, recorded as a residual.
- Dropping the 400 % zoom and the print (simplicity 12): you asked to keep the manual checks; they stay as quick confirmations.
- A memory scope through `systemd-run` (robustness 10): refused by this session's permission rules; the harness enforces its own ceiling instead.
# Annex. Facts (develop ae845c6, 2026-10-17)
Engine, consumers, tests
- `packages/pdf/src` 3,122 lines: reader (`attachment/scan.ts` 549, `inflate.ts` 83, `read.ts`), writer (`export.ts` 228, `render/*` about 1,250 incl. `observationPage.ts` 634), `branding.ts` 291, `svg/*`, `text.ts`, `render/dates.ts`, `i18n` (25 labels). Tests: 11 files, 140 cases (scan 39, inflate 9, read 13, security 55, text 5, size 2, goldens 11, raster 2, reexport 1, R3 oracle generators 3).
- App: `src/pdf/{import,export,browserRasterizer}.ts`, `EditorRoute` (type only), `scripts/compare-reports.ts` + `compare/*` (589 lines, 11 cases). Only pdf.goldens, pdf.import and pdf.roundtrip load `pdf-lib`; `apps/app/src` never does.
- `release/0.2.0` and develop carry the same `packages/pdf/src`, and the same archive, report and sheet schemas as the N-1 copy (`git diff release/0.2.0 1a7ee7d` on those directories: empty).
- Import today: whole file read on the main thread, TS scan, `JSON.parse(new TextDecoder().decode(data))` (scan.ts:498), candidate kept when it is an object with a numeric `version` or `envelopeVersion`, `JSON.stringify` of that object into the core's `archive.import` (sheetOps.ts:33). The byte scan runs before the core loads. A trap spends one of the main instance's 3 recoveries.
- Rescue copy today: routed on the first KiB, ≤ 16 MiB, `TextDecoder('utf-8', { fatal: true })`, `draft.restore` on the main instance.
- Export failures today: any throw → `editor.export_failed` or the stopped text (`EditorRoute.tsx:252-254`).
pdf-lib 1.17.1 as used
- Fonts Helvetica, Helvetica-Bold, Times-Roman, WinAnsi, not embedded; width `total * (size / 1000)`, `widthOfGlyph || 250`, KPX kerning; glyphs drawn unkerned.
- Operators: text `q BT rg Tf TL Tm (<hex> Tj T*)+ ET Q` (TL 24); image `q cm cm cm cm Do Q`; line `q RG w d m m l S Q`; rectangle `q rg w d cm cm cm m l l l h f Q`; operands by `numberToString`; no opacity, no ExtGState; a new resource name `Tag-<10 digits>` per draw call (seeded RNG); streams Flate (pako level 6); classic xref (`useObjectStreams: false`), no `/ID`.
- Images: `embedPng` decodes at call time (UPNG, RGBA8) and holds the RGB plane (and an alpha plane when an alpha < 255) until `save()` deflates them; no dedup.
- Info: Title, Author, Subject, Keywords (`faunosteo-archive/1`), Producer and Creator (`pdf-lib (https://github.com/Hopding/pdf-lib)`) as UTF-16BE hex with BOM; CreationDate and ModDate = `exportedAt`, literal `D:YYYYMMDDHHMMSSZ`.
- Attachment: `JSON.stringify(envelope, null, 2)`, report written as the store object (insertion order); EmbeddedFile `/Subtype /application#2Fjson`, Params; Filespec `/F (osteo-report.json)`, `/UF` and `/Desc` hex, `/AFRelationship /Data`; catalog `Names/EmbeddedFiles` (hex key) and `/AF`.
- Links: `Border [0 0 0]`, URI action holding the hex of the ASCII bytes.
- Dates: `Intl.DateTimeFormat` fr-FR and en-US, long month, UTC; `^\d{4}-\d{2}-\d{2}$` else unchanged; `Date.UTC` maps 0 to 99 to 1900 to 1999; rolled-over dates unchanged.
- Caps: 500 observations × 8 distinct views; the draft sheet has two views; rasters 1200 px wide, aspect clamped to 0.2 to 2.0; views of an observation rasterised under `Promise.all`, embedded in order; only the base64 branding PNGs pass the PNG gate.
Measurements (Node 24, TS engine, resvg rasteriser, fr): v2full nologos 3 views, PNG 1.63 MB, PDF 1.17 MB, attachment stored 54 KB; demo nologos 7 views, 3.75 MB, 2.64 MB, 55 KB; demo logos 8 rasters, 3.79 MB, 2.82 MB; v2unresolved logos 1 raster, 0.26 MB. Per view: PNG 526 to 553 KB, decoded RGBA 4.4 to 4.5 MB, ≈ 0.37 MB of image stream.
Experiments: `String::from_utf8_lossy` after one BOM = `new TextDecoder().decode` on 200,015 byte strings, 0 differences; serde_json refuses `1e400`, matches the JS path on `1e-400`, `-0`, big integers, long decimals and duplicates once printed by `js_number`; a lone surrogate escape fails in serde_json (`lone_surrogate` since R2).
Browsers and tooling: module workers Chrome 80, Firefox 114, Safari 15; `DecompressionStream` Chrome 80, Firefox 113, Safari 16.4; Vite 7.3.6 default target chrome107, firefox104, safari16, production workers `iife` by default, dev classic workers keep ESM imports; CSP in DEPLOY.md `script-src 'self' 'wasm-unsafe-eval'`, no `worker-src`, `docker/nginx.conf` sends none; playwright-core 1.64.0 outside the repository, Chromium present, Firefox 157 installed and proven headless (classic and module workers with wasm), WebKit 27.2 downloaded and blocked by two missing system packages; WASM 395.6 KB gzip of 600 KB, linear memory 4.1 MiB after the editor path, sheet bundle text about 522 KB; the wasm-bindgen glue keeps its instance in a module variable (BLK-012: dead instances retained until reload); R2 and R3 kept no per-test traceability table.