chore(memory): R4.9 plan in the TODO (bench, classification, recettes, checks, audits, docs, checkpoint) and the verify contract

This commit is contained in:
bchanot committed 2026-10-20 21:03:54 +02:00
1 parent f36dbdd4ae
commit 58b5688dc7
2 files changed
+231 -1

No files matched your search

+9 -1
View File
@@ -261,7 +261,15 @@ feat/findings-tree-v2 merged (FindingsTreePicker tracked in HEAD); all work belo
- [x] R4.8c ledger: `scripts/r4-ledger.mjs` reads the frozen 301 cases from the committed TSV (no vitest run of deleted suites), re-derives dispositions (deleted suites → `deleted` with their cargo / vitest target, N-1 switch noted, read-back notes), census: every cargo target in `cargo test --list`, every vitest target in the live report, counts = 301; TSV regenerated
- [x] R4.8d non-regression proofs (owner §3): grep census test (no `@faunosteo/pdf`, `pdf-lib`, `@faunosteo/domain` import under apps/app/src, packages/core-wasm/src; the import worker path, the export session path and the root `report:compare` script named by a test), wasm:build, rust-check, pnpm check, pnpm check:all (app image, worker test + image), N-1 reader suites, O2/O3/O7/O8 fixtures still read, 612 leaves, rescue copies and quarantine suites
- [x] R4.8e (done 2026-10-19; STOP before R4.9) docs: RUST.md §10.10 (deleted files and packages, dependencies removed, Rust-only features, TS still legitimate with reasons, tests, risks, R5 prerequisites), CLAUDE.md (stack table, map, PDF conventions, workflow lines), DEPLOY.md (module size, rollback), PDF-FORMAT, PDF_IMPORT_HARDENING §5, TEST_STRATEGY, WORKSPACE, packages/README, fixtures README, CHANGELOG (Unreleased), README; memory (BDR, journal); report, STOP before R4.9
- [ ] R4.9 verifier + security + owner final acceptance → merge on owner signal
- [ ] R4.9 final verification, independent audits, J1/J2 recettes (owner go 2026-10-20, R4.8 validated; no merge, no R5, stop at the checkpoint)
- [ ] R4.9a memory bench (owner §3: the Chromium 10 MiB reserve of R4.6 is NOT closed by R4.8): `scripts/browser/r4-memory-bench.mjs` on the series machinery, one editor tab, demo + L, ≥ 6 exports after the init export, reproducible; five readings told apart per step: (1) wasm linear memory (`WebAssembly.Memory` captured at instantiation), (2) content-process RSS (watchdog), (3) live canvases / images / bitmaps / blobs / object URLs (FinalizationRegistry counters + createObjectURL/revoke ledger; Chromium heap-snapshot class census), (4) transient peak during the export (RSS sampler), (5) retained after the exports: settled, after the 30 s `downloadBlob` revocation window, after leaving the editor (Home) + GC; three engines; results JSON + table in RUST.md §10.11; cause / severity / fix proposed if a durable retention is confirmed, nothing declared resolved without a measure
- [ ] R4.9b import security classification (owner §4): every open point of PDF_IMPORT_HARDENING §5 and of BDR-058 / BDR-059 / BDR-063 in one table: fixed with proof / accepted temporarily with justification / blocking before merge / before public exposure or upload activation; written in PDF_IMPORT_HARDENING.md §6, hostile refusals kept, no silent change of user data
- [ ] R4.9c J1 + J2 recettes refreshed (owner §5): `R4_J1.md` / `R4_J2.md` on the R4.8 state (export on the core, no TS engine), device list per plan OD-6 verbatim (computer: Chrome + Firefox; iPhone: Safari iOS; low-end Android: its browser), kits regenerated (`r4-j1-kit`, `r4-j2-kit`) and checked, `pnpm report:compare` step in J2, results templates NON TESTÉ untouched; announce TEST FONCTIONNEL J1 DISPONIBLE + TEST FONCTIONNEL ET GRAPHIQUE J2 DISPONIBLE; no human test declared done
- [ ] R4.9d full checks: `pnpm check:all`, PGlite suite, wasm size line (519,795 B gzip accepted; budget 600 KB / report 550 KB kept, proofs test unchanged), oracles + goldens diff vs R4.1 freeze = empty
- [ ] R4.9e independent audits (owner §6): contract `.claude/tasks/contracts/2026-10-20-rust-r4-final-1000.md` (owner §2 list as criteria), fresh verifier + fresh security audit in parallel; real anomalies fixed minimally with regression tests + targeted re-audit; oracles/goldens unchanged
- [ ] R4.9f docs + memory: RUST.md §10.11 (bench, classification, audits, checks, residuals), CHANGELOG, TODO; BDR / EVAL / journal; commits on `feature/rust-r4-pdf-core` (hooks push)
- [ ] R4.9g checkpoint report (owner §9: verifier, security, checks, memory + reading, residual risks, real merge blockers, J1/J2 instructions, git state) → STOP; merge and R5 only on the owner's explicit signal
- [ ] owner action (non-blocking): `packages/pdf/node_modules` leftover (13 pnpm symlinks, 6 bin shims, 1 vitest cache file, 0 tracked or useful files) → `rm -rf packages/pdf/node_modules && rmdir packages/pdf` (the recursive delete was refused to Claude by the permission layer)
- [ ] 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
@@ -0,0 +1,222 @@
# CONTRACT — rust-r4-final (R4.9)
- date: 2026-10-20 | flow: verify (R4.9 gates) | branch: feature/rust-r4-pdf-core
- status: active
- plan: `.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md` (rev 2, owner-validated 2026-10-18, §A.6 conditions; slice R4.9 in §B.7), TODO `R4.9a–g`
- base: 66909b6 (develop tip the branch was cut from); freeze commit aada799 (R4.1, frozen oracles); d492bf7 (R4.6, the declared re-freeze of the R4 digests); run every CHECK from the repository root
## REQUEST (verbatim — IMMUTABLE)
# FAUNOSTEO — Validation R4.8 et lancement R4.9
Je valide officiellement R4.8.
Les suppressions des anciennes implémentations PDF TypeScript, le nettoyage des dépendances, le recensement des consommateurs et les remplacements de tests sont approuvés.
Les résultats annoncés de `pnpm check:all` sont satisfaisants.
Tu peux commencer **R4.9 : vérification finale, audits indépendants et préparation des recettes J1/J2**, conformément au plan R4.0 validé.
## 1. Nettoyage R4.8 approuvé
Je valide :
- La suppression de `packages/pdf`.
- La suppression de l'ancienne CLI de comparaison TypeScript.
- La suppression des dépendances PDF devenues inutiles.
- La conservation des oracles, goldens, PDF historiques et lecteurs N-1.
- La conservation temporaire de `packages/anatomy` et `packages/domain` pour R5.
- Le registre LEDGER.tsv avec 301 cas, aucun en attente.
- Les contrôles de recensement empêchant la réintroduction des anciens moteurs métier.
Ne supprime aucun autre composant encore nécessaire au pipeline anatomique.
Le reliquat local `packages/pdf/node_modules` peut être nettoyé après vérification de son contenu et de l'absence de fichiers utiles non suivis. Ce nettoyage n'est pas bloquant.
## 2. Objectif de R4.9
Réaliser les contrôles finaux de R4 sans recommencer les développements ni l'étude architecturale.
Je souhaite une vérification indépendante :
- Des contrats de lecture et d'écriture PDF.
- De la compatibilité v2/v3.
- Des archives et pièces jointes.
- Du rendu anatomique.
- Des comportements de refus contrôlés.
- De la conservation des données sur erreur.
- De la suppression effective des moteurs TypeScript remplacés.
- De la couverture de tests conservée après nettoyage.
Les oracles et goldens doivent rester inchangés.
## 3. Mémoire : point important avant la fusion
Ne considère pas la réserve Chromium de R4.6 comme résolue par le nettoyage R4.8.
Effectue le banc mémoire prévu et distingue :
1. Mémoire linéaire WASM.
2. Mémoire globale des processus navigateur.
3. Rétention des canvas, images, Blob et URL objet.
4. Allocations transitoires.
5. Mémoire durablement retenue après les exports et retours au repos.
Comparer les comportements sur plusieurs exports successifs avec un protocole reproductible.
Distinguer coût d'initialisation, pic temporaire et croissance persistante.
Si une rétention durable problématique est confirmée, présenter sa cause, sa gravité et le correctif proposé avant de clore R4.
Ne pas déclarer un problème résolu sans mesure.
## 4. Sécurité de l'import
Reprendre les réserves de `PDF_IMPORT_HARDENING §5` et les décisions BDR-058, BDR-059 et BDR-063.
Classer chaque risque :
- Corrigé avec preuve.
- Accepté temporairement avec justification.
- Bloquant avant fusion.
- À traiter avant exposition publique ou activation des uploads concernés.
Les refus de fichiers hostiles déjà validés restent acquis.
Aucune donnée utilisateur ne doit être supprimée ou modifiée silencieusement.
## 5. Recettes J1 et J2
Préparer les procédures existantes, sans les réinventer.
Je dois pouvoir tester depuis mes appareils réels, via l'accès LAN :
**J1 :**
- Imports PDF sur les navigateurs et appareils prévus.
- PDF historiques v2.
- PDF v3.
- Fichiers volumineux.
- Imports répétés.
- Comportements WebKit/Safari.
- Messages et conservation des données sur erreur.
**J2 :**
- Export PDF FR/EN.
- Vues anatomiques et détails.
- Marqueurs et surlignages.
- Pièces jointes et archives.
- Relecture et réimport.
- Comparaison avec `pnpm report:compare`.
- Tous les autres contrôles prévus dans `R4_J2.md`.
Respecter la liste exacte des appareils et navigateurs définie dans le plan R4.
Ne déclarer aucun test humain comme effectué avant mon retour.
Signaler clairement :
TEST FONCTIONNEL J1 DISPONIBLE
TEST FONCTIONNEL ET GRAPHIQUE J2 DISPONIBLE
lorsque les deux recettes sont prêtes.
## 6. Audits indépendants
Exécuter le vérificateur et l'audit de sécurité indépendants prévus pour R4.9.
Analyser toute anomalie réelle.
Pour une correction nécessaire, effectuer les tests de non-régression concernés et, selon sa portée, un nouvel audit ciblé.
Éviter les refontes sans justification.
## 7. Taille WASM
La taille actuelle de 519 795 octets gzip est acceptée pour R4.
Conserver le suivi du budget et du seuil d'alerte.
Ne pas augmenter artificiellement le budget pour masquer une régression.
La taille pourra être réévaluée au cours de R5 avec des mesures réelles.
## 8. Git et documentation
Rester sur `feature/rust-r4-pdf-core`.
Conserver les commits, pushs, audits, mémoire et documentation selon le workflow habituel.
Aucune fusion R4 dans develop avant ma validation finale.
Ne commence pas R5.
La release 0.2.0 reste en attente.
Aucune modification de production, DNS ou déploiement sur faunosteo.com.
## 9. Livraison du checkpoint
À la fin de R4.9, présente :
1. Les résultats du vérificateur indépendant.
2. Les résultats de l'audit sécurité.
3. Les résultats des tests complets.
4. Les mesures mémoire et leur interprétation.
5. L'état de chaque risque résiduel.
6. Les éventuels blocages réels à la fusion.
7. Les instructions finales des recettes J1/J2.
8. L'état Git et les derniers commits.
Si J1/J2 ne sont pas encore validées par moi, arrête-toi à ce checkpoint.
**Ne fusionne pas R4 et ne commence pas R5 sans mon accord explicite.**
## CLARIFICATIONS
Q: what counts as "the oracles and goldens"? / A: everything frozen at R4.1 (`crates/core/tests/oracles/**` but the R4.2-added `inflate.browsers.json`, `crates/core/tests/fixtures/**` but the R4.2-added `utf8-lossy.json`, `apps/app/tests/fixtures/goldens/{step6,r2,r3}/**`, `apps/app/tests/fixtures/pdf/**`), unchanged since aada799; the R4 digests `goldens/r4/pdf.*.sha256` are the writer's own bytes, re-frozen once at R4.6 (BDR-062, B2 + B4, commits 9e688b6 and d492bf7) and unchanged since; `crates/core/tests/pdf/LEDGER.tsv` is the living register (targets filled per slice), not an oracle. [gated 2026-10-20]
Q: the memory bench's five dimensions? / A: `scripts/browser/r4-memory-bench.mjs` (+ `lib/memory-probes.mjs`): (1) linear = the page's live `WebAssembly.Memory` buffers, (2) content and summed RSS from the watchdog, (3) live canvases / images / bitmaps / blobs / PDF blobs (FinalizationRegistry) and object URLs (created − revoked), Chromium heap-snapshot census, (4) the watchdog's content peak per export, (5) rest windows: settled, after the 30 s revocation, Home, Home idle. Results `scripts/browser/results/2026-10-20-r4-memory-bench.json`, reading in RUST.md §10.11. [gated 2026-10-20]
Q: where does the import security classification live? / A: `docs/development/PDF_IMPORT_HARDENING.md` §6, one row per open point of §5 and of BDR-058 / BDR-059 / BDR-063, class ∈ {fixed with proof, accepted temporarily, blocking before merge, before public exposure}. [gated 2026-10-20]
Q: J1/J2 device list? / A: plan OD-6 verbatim: the computer with Chrome and Firefox, the iPhone with Safari iOS, the low-end Android phone with its browser; every result cell stays NON TESTÉ until the owner fills it. [gated 2026-10-20]
Q: `pnpm check:all` needs Docker; may the verifier run `pnpm check` instead? / A: yes; `check:all` is run by the orchestrator and its log cited. [gated 2026-10-20]
## ACCEPTANCE CRITERIA
1. PDF read and write contracts: every cargo suite of the core (reader, inflate, JSON, layout, PNG, content, serialiser, session, budget, robustness, compare) passes with every feature on.
CHECK: cd crates && (. ../scripts/rust-env.sh; cargo test -p faunosteo-core --features cli --quiet > /tmp/r49-cargo.log 2>&1) && ! grep -q "FAILED\|panicked" /tmp/r49-cargo.log && grep -c "test result: ok" /tmp/r49-cargo.log | awk '$1 >= 25 {print "CARGO_OK"}'
EXPECT: CARGO_OK
2. v2 / v3 compatibility: the 612 legacy leaves migrate through the worker's import path and the v2 PDFs round-trip (app suites `migration.leaves`, `pdf.roundtrip`, `routes.HomeRoute.messages` on the O2 / O3 / O7 / O8 corpora).
CHECK: cd apps/app && ../../node_modules/.bin/vitest run tests/unit/migration.leaves.test.ts tests/unit/pdf.roundtrip.test.ts tests/unit/routes.HomeRoute.messages.test.ts > /tmp/r49-compat.log 2>&1 && grep -q "Test Files 3 passed" /tmp/r49-compat.log && echo COMPAT_OK
EXPECT: COMPAT_OK
3. Archives and attachments: the envelope suites and the N-1 reader read the R4 attachments; the cargo session suite proves the self-check (`archive.envelopes`, `n-1.reader`, `pdf.goldens`; cargo `pdf_session`, `pdf_serialize`).
CHECK: cd apps/app && ../../node_modules/.bin/vitest run tests/unit/archive.envelopes.test.ts tests/unit/n-1.reader.test.ts tests/unit/pdf.goldens.test.ts > /tmp/r49-arch.log 2>&1 && grep -q "Test Files 3 passed" /tmp/r49-arch.log && cd ../../crates && (. ../scripts/rust-env.sh; cargo test -p faunosteo-core --features cli --test pdf_session --test pdf_serialize --quiet > /tmp/r49-arch2.log 2>&1) && ! grep -q "FAILED" /tmp/r49-arch2.log && echo ARCHIVE_OK
EXPECT: ARCHIVE_OK
4. Anatomical rendering: the R3 compose and layer oracles and the export's request SVGs against the frozen compose oracle (cargo `anatomy_compose`, `anatomy_layer`, `anatomy_canvas_op`; core-wasm `pdf-export.session.test.ts`).
CHECK: cd crates && (. ../scripts/rust-env.sh; cargo test -p faunosteo-core --test anatomy_compose --test anatomy_layer --test anatomy_canvas_op --quiet > /tmp/r49-anat.log 2>&1) && ! grep -q "FAILED" /tmp/r49-anat.log && cd ../packages/core-wasm && ../../node_modules/.bin/vitest run tests/pdf-export.session.test.ts > /tmp/r49-anat2.log 2>&1 && grep -q "Test Files 1 passed" /tmp/r49-anat2.log && echo RENDER_OK
EXPECT: RENDER_OK
5. Controlled refusals: the hostile corpora answer closed kinds and the validated messages (cargo `pdf_robustness`, `pdf_import`, `pdf_budget`, `svg_sanitiser`; app `routes.HomeRoute.import`, `routes.HomeRoute.rescueCopy`, `routes.HomeRoute.archive`).
CHECK: cd crates && (. ../scripts/rust-env.sh; cargo test -p faunosteo-core --features cli --test pdf_robustness --test pdf_import --test pdf_budget --test svg_sanitiser --quiet > /tmp/r49-ref.log 2>&1) && ! grep -q "FAILED" /tmp/r49-ref.log && cd ../apps/app && ../../node_modules/.bin/vitest run tests/unit/routes.HomeRoute.import.test.tsx tests/unit/routes.HomeRoute.rescueCopy.test.tsx tests/unit/routes.HomeRoute.archive.test.tsx > /tmp/r49-ref2.log 2>&1 && grep -q "Test Files 3 passed" /tmp/r49-ref2.log && echo REFUSALS_OK
EXPECT: REFUSALS_OK
6. Data kept on error: a refused import, a crashed or timed-out worker, a stopped engine and a failed export leave the draft, the archive and the file untouched (app `routes.coreStopped`, `state.coreFailures`, `routes.EditorRoute.export`, `routes.EditorRoute.degraded`).
CHECK: cd apps/app && ../../node_modules/.bin/vitest run tests/unit/routes.coreStopped.test.tsx tests/unit/state.coreFailures.test.tsx tests/unit/routes.EditorRoute.export.test.tsx tests/unit/routes.EditorRoute.degraded.test.tsx > /tmp/r49-keep.log 2>&1 && grep -q "Test Files 4 passed" /tmp/r49-keep.log && echo KEPT_OK
EXPECT: KEPT_OK
7. The TypeScript PDF engines are gone and cannot return: no tracked file under `packages/pdf`, no `pdf-lib` / `@pdf-lib` / `@resvg` in the lockfile, no `@faunosteo/pdf` or `@faunosteo/domain` import under `apps/app/src` or `packages/core-wasm/src`, and the census suite passes.
CHECK: [ "$(git ls-files packages/pdf | wc -l)" = 0 ] && ! grep -q "pdf-lib\|@pdf-lib\|@resvg" pnpm-lock.yaml && ! grep -rq "@faunosteo/pdf\|@faunosteo/domain" apps/app/src packages/core-wasm/src && cd apps/app && ../../node_modules/.bin/vitest run tests/unit/r4.census.test.ts > /tmp/r49-census.log 2>&1 && grep -q "Test Files 1 passed" /tmp/r49-census.log && echo GONE_OK
EXPECT: GONE_OK
8. Test coverage kept after the cleanup: the ledger holds 301 frozen cases, none pending, every target present (`node scripts/r4-ledger.mjs` prints the census and exits 0).
CHECK: node scripts/r4-ledger.mjs > /tmp/r49-ledger.log 2>&1 && [ "$(tail -n +2 crates/core/tests/pdf/LEDGER.tsv | wc -l)" = 301 ] && ! grep -qi "pending" crates/core/tests/pdf/LEDGER.tsv && echo LEDGER_OK
EXPECT: LEDGER_OK
9. Oracles and goldens unchanged: nothing frozen at R4.1 differs from aada799 (the two R4.2 additions excepted), the R4 digests are unchanged since d492bf7.
CHECK: [ -z "$(git diff --name-only aada799..HEAD -- crates/core/tests/oracles crates/core/tests/fixtures apps/app/tests/fixtures/goldens/step6 apps/app/tests/fixtures/goldens/r2 apps/app/tests/fixtures/goldens/r3 apps/app/tests/fixtures/pdf | grep -v 'oracles/r4/inflate.browsers.json\|fixtures/pdf/r4/utf8-lossy.json')" ] && [ -z "$(git diff --name-only d492bf7..HEAD -- apps/app/tests/fixtures/goldens/r4)" ] && echo ORACLES_OK
EXPECT: ORACLES_OK
10. The memory bench ran on the three engines for demo and L with the five dimensions and the rest windows; its reading is recorded in RUST.md §10.11.
CHECK: node -e "const r=require('./scripts/browser/results/2026-10-20-r4-memory-bench.json');const ok=r.runs.filter(x=>x.outcome==='bench');const eng=new Set(ok.map(x=>x.engine));const steps=['start','init','settled','after revoke','home','home idle'];if(eng.size!==3)throw new Error('engines '+[...eng]);for(const run of ok){for(const s of steps){const row=run.rows.find(x=>x.step===s);if(!row)throw new Error(run.engine+' '+run.report+' missing '+s);for(const k of ['linear','rssContent','peakContent','live','urlsLive'])if(row[k]===undefined)throw new Error(k)}}console.log('BENCH_OK')" && grep -q "10.11" docs/development/RUST.md && echo BENCH_DOC_OK
EXPECT: BENCH_OK and BENCH_DOC_OK
11. Import security classification: `PDF_IMPORT_HARDENING.md` §6 classifies every open point of §5 and of BDR-058 / BDR-059 / BDR-063 into the four classes, and names no hostile refusal as relaxed.
CHECK: grep -q "^## 6" docs/development/PDF_IMPORT_HARDENING.md && for c in "fixed with proof" "accepted temporarily" "blocking before merge" "before public exposure"; do grep -q "$c" docs/development/PDF_IMPORT_HARDENING.md || exit 1; done && grep -q "BDR-058" docs/development/PDF_IMPORT_HARDENING.md && grep -q "BDR-059" docs/development/PDF_IMPORT_HARDENING.md && grep -q "BDR-063" docs/development/PDF_IMPORT_HARDENING.md && echo CLASS_OK
EXPECT: CLASS_OK
12. J1 and J2 recettes re-issued on the R4.8 state with the OD-6 device list, and no human test declared done: the results templates hold no PASS or FAIL cell.
CHECK: grep -q "Chrome" docs/development/R4_J1.md && grep -q "Safari iOS" docs/development/R4_J1.md && grep -q "Android" docs/development/R4_J1.md && grep -q "report:compare" docs/development/R4_J2.md && ! grep -q "TypeScript engine (R4.6)" docs/development/R4_J1.md && [ "$(grep -c '| PASS\|| FAIL' docs/development/R4_J1_RESULTS.md docs/development/R4_J2_RESULTS.md | awk -F: '{s+=$2} END {print s}')" = 0 ] && echo RECETTE_OK
EXPECT: RECETTE_OK
13. The whole Node pipeline passes (typecheck, tests, lint, build).
CHECK: ./node_modules/.bin/pnpm check > /tmp/r49-check.log 2>&1 && echo CHECK_OK
EXPECT: CHECK_OK
14. WASM size: the shipped module stays under the 600 KB budget and the size test still pins it; the budget line was not raised.
CHECK: [ "$(gzip -9 -c packages/core-wasm/pkg/faunosteo_wasm_bg.wasm | wc -c)" -le 614400 ] && grep -q "600" packages/core-wasm/tests/size.test.ts && echo SIZE_OK
EXPECT: SIZE_OK
15. Scope: no merge into develop, no R5 file, no production change: HEAD is on `feature/rust-r4-pdf-core`, develop's tip is unchanged (66909b6 is its merge-base), and no deploy or DNS file changed.
CHECK: [ "$(git rev-parse --abbrev-ref HEAD)" = feature/rust-r4-pdf-core ] && [ "$(git merge-base develop HEAD)" = "$(git rev-parse 66909b6)" ] && [ -z "$(git diff --name-only 66909b6..HEAD -- DEPLOY.md docker/nginx.conf | grep -v DEPLOY.md)" ] && echo SCOPE_OK
EXPECT: SCOPE_OK