docs(docs): RUST.md §10.9 R4.7 record (tool on the core, O10 parity 158/72, A.3 lines as printed, timing), CLAUDE.md map and command, PDF-FORMAT; TODO R4.7 closed; memory BDR-063, journal

This commit is contained in:
bchanot committed 2026-10-19 11:13:42 +02:00
1 parent 02ebf05195
commit 77e11a53e4
6 files changed
+106 -11

No files matched your search

+81 -1
View File
@@ -905,7 +905,7 @@ imports it and restyles `data-state` in place as before.
needs it.
- WASM budget: 396 KB of 600 KB used; R4 adds the PDF reader and writer.
## 10. R4: the PDF core in Rust (in progress; R4.1 freeze 2026-10-18, export switched 2026-10-19)
## 10. R4: the PDF core in Rust (in progress; R4.1 freeze 2026-10-18, export and `report:compare` switched 2026-10-19)
Plan and contract: `.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md`
(revision 2, validated by the owner 2026-10-18 with the conditions of its
@@ -1880,3 +1880,83 @@ Residual risks and open points (R4.6):
frees the session).
- The headless runs validate nothing on a device: J2 (`R4_J2.md`) on the
owner's computer and iPhone, with the J1 import recette still due.
### 10.9 R4.7: the archive check tool on the core (2026-10-19, `pnpm report:compare` switched)
What runs where. `crates/core/src/pdf/compare` (feature `cli`, which enables
the reader and the writer; never enabled by the wasm facade, so the shipped
module is unchanged: 1,535,289 B raw, 519,795 B gzip -9) holds the tool
without its file system: `compare_bytes` reads a PDF's attachment with the R4
reader (`read_attached_document`, no value cap, as the TypeScript had none),
parses it as the session does (`parse_json`), reads it through the layered
archive reader (`read_archive_document`, the R2 code the application
imports with), and prints it as `compare/report.ts` did (`lines.rs`: zone
and finding lines, `!! UNRESOLVED` with its reason, the migration lines of a
v2 archive, the header with the sheet check and the counts, the footer, the
`--full` texts), with `esc` on every untrusted string (V8's
`[\p{Cc}\p{Cf}

]`, the `SAFE_TEXT_DROPPED` table of R4.4);
`run.rs` is `main` (`parse_args`, the loop over the entries, `--summary`,
`--diff`, stdout, stderr and the exit code) over a `Files` trait. The binary
`src/bin/report_compare.rs` (the one file of the crate allowed `std::fs`
and `std::env`) loads the seed draft sheet (`sheet-ref.json`,
`document.json`, `report-migration-map.json`; no drawing: the comparison
needs none), resolves the arguments against `INIT_CWD` (the folder pnpm was
typed in, as the TypeScript did) and implements `Files` (a folder stands for
its `.pdf` files sorted; a missing, unreadable, irregular or oversized entry
is a failed entry). `pnpm report:compare` runs `scripts/report-compare.sh`
(`rust-env.sh`, then `cargo run --release --locked -q --features cli --bin
report-compare`): the first run compiles the binary (25 s on the development
machine), the next ones start at once. The TypeScript CLI
(`apps/app/scripts/compare-reports.ts`, `compare/*`) and its vitest suite stay
until R4.8 (the O10 generator still runs them), with the app's own
`report:compare` script no longer behind the root one.
Parity (cargo `pdf_compare`, 15 tests, 1.6 s): the 230 invocations of the
O10 oracle (`tests/oracles/r4/compare/compare.json`: every fixture PDF, the
step6 folder with and without options, the argument errors, the 22 runs of
the 11 `scripts.compare.test.ts` cases on their scenario PDFs) replayed
in-process through `run` on the seed sheet. The 158 rows the plan does not
declare match exactly (stdout, stderr, exit code); the 11 cases have one cargo
test each (the ledger targets, `pdf_compare::<case>`, 0 pending rows left of
301). The real binary is spawned on the six `cli` and `folder` rows and on two
scenario rows: byte-equal to the pure run and to the oracle. The 72 declared
rows (§A.3) print one closed line each, exit 2:
| TypeScript printed | Rows | Rust prints |
|---|---|---|
| a ZodError dump (the issues as JSON, escaped) | 63 | `report document invalid: <the core's detail>` (62: `missing field \`id\`` on the scan and read corpora, `missing field \`conclusion\``, `invalid type: null, expected f64` for the overflowing vertebra index); 1 decoy-first file whose decoy holds a lone surrogate: the refusal below, before any schema |
| the comparison, a lone surrogate kept in the content or a key, or overwritten by a duplicate (OD-4) | 6 | `attachment refused: lone UTF-16 surrogate escape at byte N` |
| `report version Infinity cannot be read` (2) and the report under `archive v1 (snapshot rejected: unsupported_envelope)` (1) | 3 | `report version null cannot be read`: the overflow reads as `null` in the core (`rewrite_overflow_numbers`), as the R3 application path already saw it (O8 `no_attachment` for the same three files) |
Nothing else differs: the labels, the migration lines, the `__proto__` ids,
the control characters escaped (`\u001b`, `\u000a`, `\u009b`, `‮`,
`
`, five-digit code points as `1`), the `--diff` of the
placeholder and `--full` forms, the usage and option errors on stderr with
exit 1, the failed entries with exit 2.
Time and memory (release binary, the development machine): one PDF 7 ms
(the seed read and indexed, the file compared), the three fixture folders
(72 entries, the R3 real-raster PDFs and the tolerance corpus included)
185 ms, the `r4/read` corpus (131 files) 135 ms; 6 MiB resident on the step6
folder. Through `pnpm report:compare` the launch is cargo's (about 250 ms
per invocation, the binary already built); the TypeScript CLI took 270 ms
for one PDF and 410 ms for the three folders under tsx.
Declared behaviour (plan §A.3, no other): the three lines above. The
output of every other row is the TypeScript's. `--locale`, `--summary`,
`--full`, `--diff` and the folder expansion keep their meaning; the exit
codes keep theirs (0, 1 usage or option, 2 failed entries).
Residual risks and open points (R4.7):
- The tool reads the seed from the repository checkout
(`CARGO_MANIFEST_DIR/../../supabase/seed/…`), as the TypeScript read it
from its script folder: the binary is not relocatable. A copied binary
prints the missing seed path and exits 1.
- The `report document invalid` line carries the core's serde detail
(`missing field …`, `invalid type …`, `unknown variant …`): the field name
or the offending value of the file, escaped; the TypeScript's ZodError
dump carried the same and more.
- A PDF over 50 MiB is refused by the entry check (`file too large`) before
the reader, as before; the reader's own cap would say `not a readable
PDF`.