Files
faunosteo/.claude/tasks/contracts/2026-10-20-rust-r4-final-1000.md

17 KiB
Raw Permalink Blame History

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] Q: (internal, orchestrator, after verifier pass 1) the vitest binary path of criteria 2–7? / A: oracle defect: the package-local ./node_modules/.bin/vitest of apps/app and packages/core-wasm, assertions unchanged. Criterion 4 keeps its no-feature cargo command on purpose: it is the regression proof of the default-feature build defect found by pass 1 (criterion 16). [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
  16. The core builds, lints and tests with no feature (the workspace run unifies the wasm crate's features and hid a gated path), and rust:check runs that build. CHECK: cd crates && (. ../scripts/rust-env.sh; cargo clippy -p faunosteo-core --all-targets --locked -q -- -D warnings > /tmp/r49-nofeat.log 2>&1 && cargo test -p faunosteo-core --locked -q >> /tmp/r49-nofeat.log 2>&1) && ! grep -q "FAILED|error[" /tmp/r49-nofeat.log && grep -q "cargo clippy -p faunosteo-core --all-targets --locked" ../scripts/rust-check.sh && echo NOFEAT_OK EXPECT: NOFEAT_OK