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

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

No files matched your search

+24 -21
View File
@@ -20,8 +20,9 @@ tables `species`, `anatomical_sheets` / `_versions` / `_assets`). Step 5 moved t
application onto that model: the editor renders the bundled reference sheet (the
curated equine DRAFT, `SHEET_BUNDLE=draft`), writes Report v3 and imports v2 PDFs
through a generated migration map. Step 6 made the PDF an autonomous archive: the
`packages/pdf` engine renders from explicit inputs (report, sheet snapshot, branding,
labels, rasterizer) with no network and no DOM, and the attachment is an envelope v1
PDF engine (TypeScript `packages/pdf` until R4, the Rust core `crates/core/src/pdf`
since) renders from explicit inputs (report, sheet snapshot, branding, labels,
rasterizer) with no network and no DOM, and the attachment is an envelope v1
carrying the report, a lean sheet snapshot, the branding and the labels used, so an old
bilan is reproduced identically after any catalog, wording or logo change
(`docs/PDF-FORMAT.md`). Step 7 added identity: email/password sign-up with
@@ -57,7 +58,7 @@ MVP species: equine only. Open-source MIT.
| Styling | Tailwind CSS v4 CSS-first (no postcss config) | 4.x |
| State | Zustand | 5 |
| Validation | Zod | 3 |
| PDF | pdf-lib | 1.17 |
| PDF | the Rust core's reader and writer (`crates/core/src/pdf`, R4; no PDF library) | — |
| SVG raster | native Image/canvas (no dependency) | — |
| Animation | motion | 11 |
| Tests | vitest + happy-dom + @testing-library/react | 3.x |
@@ -191,7 +192,6 @@ faunosteo/
├─ apps/app/ ← @faunosteo/app (everything below until packages/)
├─ public/ ← favicons, env.js, site header logo only (PDF logos live in src/assets/brand; no anatomy asset)
├─ vite/sheet-bundle.ts ← Vite plugin: `virtual:faunosteo-sheet` (SHEET_BUNDLE=draft|none)
├─ scripts/compare-reports.ts ← the frozen TS archive check CLI (pure part in scripts/compare/report.ts): O10 reference until R4.8, no longer behind `pnpm report:compare`
├─ src/
│ ├─ assets/brand/ ← the four PDF branding logos, bundled by Vite (?inline / ?raw / ?url), never fetched
│ ├─ app/
@@ -234,8 +234,8 @@ faunosteo/
│ │ ├─ shell/{AppLayout,SidebarNav,MobileDrawer,UserBadge,SignOutButton}.tsx
│ │ └─ account/{SectionCard,SaveRow,AvatarSection,PersonalInfoForm,ProfessionalInfoForm,PreferencesForm,SecurityPanel,RoleBadges}.tsx
│ ├─ account/avatarTransport.ts ← magic-byte sniff (never SVG), createImageBitmap → canvas ≤ 1024 px → JPEG transport blob
│ ├─ pdf/ ← the app side of the PDF (export on the core's session since R4.6; the TS reader of packages/pdf until R4.8)
│ │ ├─ export.ts + labels.ts + import.ts ← exportReportToPdf (snapshot + branding + labels → ExportSession, rasters one by one, Blob of the parts, abort on unmount), defaultPdfLabels (25 keys), importReportFromPdf (tests; the app imports through the worker)
│ ├─ pdf/ ← the app side of the PDF (export on the core's session since R4.6; the import runs in the worker, `core/worker`)
│ │ ├─ export.ts + labels.ts ← exportReportToPdf (snapshot + branding + labels → ExportSession, rasters one by one, Blob of the parts, abort on unmount), defaultPdfLabels (25 keys); the tests' in-process import lives in tests/helpers/pdfImport.ts (the module's reader)
│ │ └─ branding.ts + browserRasterizer.ts ← bundled src/assets/brand logos (?inline / ?raw) → Branding; Image/canvas Rasterizer adapter
│ ├─ lib/{dates,id,assert,supabase}.ts ← supabase.ts: getSupabaseClient() | null
│ ├─ styles/{index,tokens}.css ← Tailwind v4 CSS-first
@@ -259,8 +259,7 @@ faunosteo/
├─ packages/domain/ ← @faunosteo/domain (pure, no DOM, zod only): anatomical-sheet (document, integrity rules, sheet-index), report (v3, v2 migration, rebase), archive (sheet snapshot, envelope v1, branding, labels, layered reader)
│ ├─ src/anatomical-sheet/{schema,validate,create}.ts ← canonical sheet document + integrity rules
│ └─ tests/{fixtures/horse-slice.ts,*.test.ts}
├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, frozen TS annotation-layer renderer + view composer (`./render`: PDF engine until R4, pipeline until R5; the app no longer depends on it)
├─ packages/pdf/ ← @faunosteo/pdf: the frozen TypeScript PDF engine (R3 reference until R4.8; no app consumer since R4.6 but the kept reader) — src/{export,read,text,branding}.ts, attachment/, svg/{parse,sanitize,view}.ts, render/, i18n/; tests reproduce the Step 6 goldens
├─ packages/anatomy/ ← @faunosteo/anatomy: legacy importer, curation pipeline, frozen TS annotation-layer renderer + view composer (`./render`: the pipeline until R5; no app and no PDF consumer since R4.8)
│ ├─ src/legacy/{svg,catalog,regions,ids,report,importer}.ts, src/cli/import-equine.ts
│ ├─ src/curation/{schema,targets,fields,ops,rename,apply,types,assets,labels,stats,changelog,review-report,overlay,seed,sources,pipeline}.ts ← changeset → draft
│ └─ tests/ ← counts preserved, special cases, determinism, curation ops, golden artifacts
@@ -334,13 +333,18 @@ PDF export (app side: apps/app/src/pdf; writer: crates/core/src/pdf/write, RUST.
→ a trap poisons the runtime as any core call; a session of a dropped instance answers core_unavailable; leaving the editor aborts and frees
→ export_from_envelope (cargo only) re-exports an archive from its own snapshot, branding and labels (no sheet)
PDF import
→ readAttachment(bytes) → engine byte scan for the EmbeddedFile stream (TS until R4; no pdf-lib parse on untrusted
bytes, BLK-009): named osteo-report* first, capped native inflation, JSON depth pre-scan
→ loadSheetIndex (core loads here) → importAttachment(data, index) → core archive.import: layered reading (report:
v3 as is, v2 migrated, else incompatible_version; envelope metadata tolerant, snapshot/branding/labels strict →
archive kept or snapshotRejected) + rebase on the loaded sheet (unresolved flags, labels kept), one call
→ hydrateImport({ report, archive }) → one alert (archive_ok / snapshot_rejected / rebased / migrated) → navigate /editor
PDF import (R4.3, RUST.md §10.5; the core's reader `crates/core/src/pdf/read`, never a PDF library)
→ HomeRoute: routing on the first KiB and the size pre-checks → startImport (core/worker/controller) → a module worker
created for the file (import.worker.ts, handler.ts): the compiled module posted by the page, a SheetHandle of the
bundled sheet, the file streamed in chunks into the module's memory (FileBytes), `import_pdf_bytes`
→ in the core: byte scan for the EmbeddedFile stream (BLK-009: no object-graph parse): named osteo-report* first, capped
inflation (16 MiB budget shared by the candidates), JSON prescan (depth, value count OD-3), the JavaScript-path
decoding (`json_js`), then archive.import: layered reading (report: v3 as is, v2 migrated, else incompatible_version;
envelope metadata tolerant, snapshot/branding/labels strict → archive kept or snapshotRejected) + rebase on the
loaded sheet (unresolved flags, labels kept), one call
→ the settlement mapped by core/worker/outcome.ts (closed kinds; timeout, crash and read error told apart: OD-5),
the worker terminated → hydrateImport({ report, archive }) → one alert (archive_ok / snapshot_rejected / rebased /
migrated) → navigate /editor; a rescue copy (JSON) follows the same worker path (`restore_copy_bytes`)
Identity (Step 7, docs/development/IDENTITY.md)
→ AuthProvider: authStore.start() = client.auth.initialize() (PKCE code in URL) + onAuthStateChange
@@ -403,7 +407,7 @@ Database (Supabase)
### Annotation rendering
- docs/ANNOTATION-RENDERING.md is the source of truth: the drawing carries no annotation element, the markers are
drawn from the document (Rust core for the canvas since R3, `crates/core/src/anatomy`; the frozen TS renderer
`@faunosteo/anatomy/render` for the PDF engine and the pipeline until R4/R5, same output), with the attributes listed there
`@faunosteo/anatomy/render` for the pipeline until R5, same output), with the attributes listed there
- Every SVG the product draws goes through the core's one reader (`anatomy::svg::read_svg`): caps before any parse,
allowlist, reference graph; a product drawing with anything removed is refused at load, never repaired
- Never rely on element id, className or a label for click targeting or behaviour — always `data-anno-id`
@@ -414,7 +418,7 @@ Database (Supabase)
### Schemas
- The data contracts live in Rust since R2 (`crates/core/src/domain/{sheet,report,archive}`, Zod semantics
reproduced: strict where Zod was strict, optional absent, nullable required, Zod schema field order);
`packages/domain` is frozen (no new logic) for the PDF engine, the pipeline and the compare CLI until R4/R5,
`packages/domain` is frozen (no new logic) for the pipeline until R5 (the app no longer depends on it: R4.8),
and its Zod copy under `packages/core-wasm/tests/n-1` is the permanent N-1 reader. Never change a contract
without bumping the version on a breaking change (additive optional fields keep it); a change touches the
Rust struct, the regenerated ts-rs types and the N-1 test
@@ -435,7 +439,7 @@ Database (Supabase)
- A4 portrait: 595.28 × 841.89 pt
- No raw URLs in PDF output — abbreviated citations only
- JSON attachment filename must start with osteo-report; content = report archive envelope v1 (report v3 + sheet snapshot + branding + labels); import accepts bare v2 (migrated), bare v3 and envelope v1; a bad snapshot never loses the report
- The writer (`crates/core/src/pdf/write`, since R4.6; the frozen TS engine `packages/pdf` until R4.8) takes no clock and no I/O; rasterisation is the browser's, one raster per core request; every SVG it composes went through the core's one reader. The export is an incremental session (OD-2): the file is written as the rasters arrive, held once, handed out in parts; never accumulate rasters or build the file twice
- The writer (`crates/core/src/pdf/write`, since R4.6; the TypeScript engine deleted at R4.8) takes no clock and no I/O; rasterisation is the browser's, one raster per core request; every SVG it composes went through the core's one reader. The export is an incremental session (OD-2): the file is written as the rasters arrive, held once, handed out in parts; never accumulate rasters or build the file twice
- Page layout is frozen by the Step 6 goldens and the R4 oracles (O1 draw logs, O2 PDFs): any visible change needs a user decision and a golden regeneration; the R4 digests (`goldens/r4/pdf.*.sha256`) pin the writer's own bytes and are rewritten only for a declared structural change, with the O2 comparisons re-run
- Fonts are StandardFonts (Helvetica/TimesRoman, WinAnsi encoding) — TTF Inter/Fraunces planned but not yet embedded. Any non-Latin-1 glyph in PDF text must use an ASCII surrogate until the TTF migration lands (e.g. `(!)` instead of `⚠`).
@@ -562,7 +566,6 @@ RUST.md §9; validated and merged 2026-10-17). Next: R4 (PDF core), R5 (pipeline
| tailwindcss 4 | CSS-first utility framework |
| zustand 5 | Lightweight global state |
| zod 3 | Schema validation + type inference |
| pdf-lib 1.17 | Pure-JS PDF generation + native attachments |
| motion 11 | Animations (modals, toasts, observation cards) |
| vitest 3 | Test runner |
| happy-dom | DOM environment for tests |
@@ -585,9 +588,9 @@ RUST.md §9; validated and merged 2026-10-17). Next: R4 (PDF core), R5 (pipeline
- Annotation rendering changes require updating docs/ANNOTATION-RENDERING.md first.
- Never modify the legacy sources under `supabase/seed/anatomical-sheets/equine/legacy-sources/` — they are the
importer's input (the user's historical files).
- Ask before any change to `readReportArchive`, `readArchiveDocument`, `readAttachedDocument` or `rebaseReportOnSheet`, and to their Rust ports (`crates/core/src/domain/{archive/read,report/rebase,report/read,session}.rs`) — they handle user data; archive readers never drop a schema version (envelope v1, Report v2/v3, sheet document v2).
- Ask before any change to the readers of user data: `crates/core/src/domain/{archive/read,report/rebase,report/read,session}.rs` and the PDF reader `crates/core/src/pdf/{read,json_js,import}.rs` (the TypeScript originals `readReportArchive`, `readArchiveDocument`, `readAttachedDocument`, `rebaseReportOnSheet` left with `packages/pdf` at R4.8; the frozen N-1 copies under `packages/core-wasm/tests/n-1` are never edited); archive readers never drop a schema version (envelope v1, Report v2/v3, sheet document v2).
- Import never parses untrusted PDF object graphs: the attachment is located by byte scan and inflated under the 16 MiB cap (BLK-009). Opening the import to external users is gated by `docs/development/PDF_IMPORT_HARDENING.md` §5 (BDR-040).
- After PDF roundtrip tests fail: check attachment bytes, then the layered reader (report first, envelope metadata, snapshot/branding/labels), then DecompressionStream inflation. Goldens under `apps/app/tests/fixtures/goldens/step6` are never regenerated without a user decision.
- After PDF roundtrip tests fail: check the attachment bytes (the N-1 scanner reads them in the envelope suites), then the layered reader (report first, envelope metadata, snapshot/branding/labels), then the core's inflation (`pdf/read/inflate.rs`). Goldens under `apps/app/tests/fixtures/goldens/step6` and the R4 digests under `goldens/r4` are never regenerated without a user decision.
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.
- Rust: native on the Ubuntu development machine (user-level rustup, never a global package, never on the VPS); `pnpm rust:check` and `pnpm wasm:build` run natively, the `:docker` variants reproduce them in the builder image. Before every Rust commit: `pnpm rust:check` green, `pnpm worker:test` green when `crates/worker` changed (Docker only: the sandbox tests and the seccomp derivation never run natively), the ts-rs types under `packages/core-wasm/types` committed, `Cargo.lock` committed. Before a merge: `pnpm check:all`. No CI runs on the forge: a workflow file is never cited as a passed check. The core takes ids, time and bytes as inputs (clippy `disallowed_methods`); the worker child is the only process that decodes untrusted bytes.
- Storage or worker change: `pnpm e2e:avatar` (worker container against the local stack, `packages/supabase/tests/e2e`) in addition to `pnpm worker:test`; `docker compose --profile worker` serves the worker from `.env.worker` (never the app `.env`).