docs(docs): R2 — RUST.md §8 (migrated components, operations, runtime, census, proofs, measurements, behaviour differences, risks), CLAUDE.md, DEPLOY.md (CSP before an R2 image, never built on the VPS), WORKSPACE, TEST_STRATEGY, packages README, CHANGELOG

This commit is contained in:
bchanot committed 2026-10-14 00:51:44 +02:00
1 parent 7be94d4ce6
commit 8e8c58efca
7 files changed
+306 -76

No files matched your search

+48 -31
View File
@@ -35,6 +35,12 @@ routes stay unauthenticated. Step 8 (= Rust R1) added the files foundation: the
the Rust worker `crates/worker` (keyed job loop + keyless sandboxed decode child)
producing 512 × 512 WebP avatars, a deferred purge queue, and the profile photo in
Mon compte, the sidebar, the drawer and the top bar (`docs/development/STORAGE.md`).
Rust R2 moved the application's domain rules into `crates/core` (sheet, report and
archive contracts, integrity rules, sheet index, migration, rebase, snapshot, layered
archive reading, editor reducers, findings and vertebra rules, report operations),
reached through the wasm facade and `packages/core-wasm`, loaded lazily by the sheet
pages only (`docs/development/RUST.md` §8); `packages/domain` is frozen for the PDF
engine, the pipeline and the compare CLI.
MVP species: equine only. Open-source MIT.
---
@@ -198,10 +204,10 @@ faunosteo/
│ ├─ auth/{validation,redirects,useAuthFailureMessage}.ts ← Zod schemas (i18n keys), safe next path, failure phrasing
│ ├─ account/{validation,useProfileForm}.ts ← account section schemas + one-save form hook
│ ├─ config/env.ts ← runtime config resolution
│ ├─ sheets/{provider,useSheet}.ts ← SheetProvider interface, bundled implementation, per-species hook
│ ├─ sheets/{provider,useSheet}.ts ← raw bundled payload; useSheet loads it into the core (ready / none / core_unavailable / invalid_sheet + retry), useSheetAvailability without the core
│ ├─ core/{runtime,sheetOps,reportOps}.ts ← the page's CoreRuntime (Vite asset URLs, lazy), typed sheet-bound and free core operations
│ ├─ services/
│ │ ├─ sheetIndex.ts ← read-only lookups over the loaded sheet (ids, never labels)
│ │ ├─ zoneInteraction.ts ← pure click decision + observation reducers (zones, sides, vertebrae)
│ │ ├─ sheetIndex.ts ← SheetIndex class: reads the core's SheetIndexData (ids, never labels) + `ops`
│ │ └─ localeSync.ts ← profiles.locale ↔ localeStore (account wins on sign-in)
│ ├─ i18n/
│ │ ├─ types.ts ← Locale type + Dict type
@@ -210,7 +216,7 @@ faunosteo/
│ │ └─ useT.ts ← useT() hook (reads localeStore)
│ ├─ state/
│ │ ├─ authStore.ts ← session, user, profile, roles, recovery flag (onAuthStateChange)
│ │ ├─ reportStore.ts ← Zustand store (Report v3) + persistence.ts (sessionStorage adapter, v2 draft migration)
│ │ ├─ reportStore.ts ← Zustand store (Report v3, core-built reports, actions answer { ok }) + persistence.ts (raw texts, quarantine keys)
│ │ ├─ localeStore.ts ← locale Zustand store (persisted to localStorage)
│ │ └─ practitionerCache.ts ← localStorage prefill
│ ├─ anatomy/drawing.ts ← sanitised asset + generated annotation layer → inline <svg> per view
@@ -271,15 +277,15 @@ faunosteo/
│ │ └─ draft/ ← GENERATED working revision: document, cleaned horse.svg, sheet-ref, report-migration-map, CHANGELOG, REVIEW-REPORT, review/*.svg, equine_draft.sql
│ └─ tests/*.sql ← pgTAP: allowed + denied paths per policy
├─ packages/README.md ← shared packages index
├─ packages/core-wasm/ ← @faunosteo/core-wasm: loader of the browser module (pkg/ built, git-ignored), ts-rs types (committed), R0 proofs (panic, serialisation, size)
├─ packages/core-wasm/ ← @faunosteo/core-wasm: CoreRuntime (lazy, poison, recovery) + Node source, pkg/ shipped and pkg-proofs/ (built, git-ignored, BUILD_STAMP), ts-rs types (committed), frozen N-1 reader (tests/n-1), tests
├─ crates/ ← Rust workspace (Cargo.toml, rust-toolchain.toml, deny.toml, clippy.toml, .cargo/config.toml at the root)
│ ├─ core/ ← faunosteo-core: contracts (report types), js_number + JS pretty formatter, facade `call(op, json)`; no I/O, no clock (lint-enforced)
│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, R0 trap proofs)
│ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing); tests/{oracles,conformance,fixtures} frozen from the TypeScript; no I/O, no clock (lint-enforced)
│ ├─ wasm/ ← faunosteo-wasm: wasm-bindgen facade (core_version, call, SheetHandle; trap exports in the proofs build only)
│ └─ worker/ ← faunosteo-worker: plain main; `decode` sandboxed child (rlimits, seccomp allowlist, image → libwebp), parent Spawner + RIFF check; R1 `run` loop: config, log (JSON lines, allowlist), keys, backend trait + http (ureq, PostgREST rpc + Storage objects), job, sweep, watchdog; Dockerfile, scripts/derive-seccomp.sh
├─ scripts/{rust-env,rust-check,wasm-build,check-all,avatar-e2e}.sh ← native Rust gate, wasm build, the pre-merge gate (`pnpm check:all`), the real-stack avatar e2e
├─ scripts/{rust-env,rust-check,wasm-build,check-all,avatar-e2e}.sh, wasm-stamp.mjs ← native Rust gate, wasm build (pkg + pkg-proofs + stamp), the pre-merge gate (`pnpm check:all`), the real-stack avatar e2e
├─ scripts/{dev-env,supabase,dev}.sh ← the DEV origin (LAN address) in one place; CLI wrapper; `pnpm dev` on that origin
├─ docker-compose.yml ← `app` service; `worker` service under the `worker` profile (read-only, cap_drop ALL, external Supabase network, `.env.worker`)
├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proof
├─ docker/rust-builder.Dockerfile, rust-run.sh, csp-proof/ ← reproducible Rust builder (alternative) + the CSP proofs (R0 module, R2 app image: app-image.sh)
├─ .gitea/workflows/ci.yml ← PREPARED, never executed (no runner): rust job (builder image, scripts/rust-check.sh, types drift, wasm), install, typecheck, test, lint, build, docker (app + worker test stage + runtime)
├─ .gitea/workflows/{rust-advisories,release-images}.yml ← nightly RustSec advisories; manual digest-tagged image publication (no deploy)
├─ .claude/{tasks/TODO.md,memory/,audits/}
@@ -299,20 +305,22 @@ User interaction
→ Zustand store (reportStore)
→ Components read store via selectors (no prop drilling)
Sheet loading
→ useSheet(speciesId) → SheetProvider (bundled: virtual:faunosteo-sheet, SHEET_BUNDLE=draft)
→ Zod-validated document + assets + migration map → buildSheetIndex()
Sheet loading (Rust core, RUST.md §8)
→ useSheet(speciesId) → SheetProvider (bundled: virtual:faunosteo-sheet, SHEET_BUNDLE=draft) → raw payload
→ coreRuntime().ready() (lazy; core_unavailable + retry on failure) → SheetHandle(payload): strict parse of the
document and migration map, index → index_data → SheetIndex (tables only) + ops (sheet-bound core calls)
SVG interaction
→ AnatomyCanvas builds the view: sanitised asset + renderAnnotationLayer() (markers from the document)
→ delegated click on [data-anno-id] → decideZoneClick() (services/zoneInteraction, pure)
→ AnatomyCanvas builds the view: sanitised asset + renderAnnotationLayer() (markers from the document; TS until R3)
→ delegated click on [data-anno-id] → sheet.ops.zoneClick(observation, id) (one core call: decision + new observation)
→ open_view → DetailModal (same drawing, view_box crop, or the view's own asset)
→ open_vertebra_picker / open_laterality_picker → pickers → reducers (ensureZone, addSides, syncVertebrae)
→ toggle / remove_both_sides → updateObservation() in store
→ open_vertebra_picker (initial selection from the core) / open_laterality_picker (sides present) → pickers
→ vertebra.select per tap, vertebra.sync / zone.add_sides on confirm → updateObservation() in store
→ toggle / remove_both_sides → the core's observation → updateObservation(); findings picker → finding.toggle
PDF export (app side: apps/app/src/pdf, engine: packages/pdf)
→ exportReportToPdf(report, index, { locale })
→ buildSheetSnapshot(index.sheet, report) + loadBranding() (4 logos bundled at build time, no network) + defaultPdfLabels
→ index.ops.snapshot(report) (core: archive.snapshot) + loadBranding() (4 logos bundled at build time, no network) + defaultPdfLabels
→ exportReportArchive({ report, sheet, branding, labels, locale, rasterizer: browserRasterizer, exportedAt })
assertSnapshot (caps, integrity, sheet invariant) → fonts (WinAnsi StandardFonts, safeText guard)
→ per observation: composeHighlightedViewSvg (xmldom: sanitise allowlist → composeViewSvg highlight) → rasterizer → page
@@ -321,11 +329,11 @@ PDF export (app side: apps/app/src/pdf, engine: packages/pdf)
→ exportFromEnvelope(envelope, …) re-exports an archive from its own snapshot, branding and labels (no sheet)
PDF import
→ importReportFromPdf(bytes, migrationMap) → readReportArchive (engine)
→ byte scan for the EmbeddedFile stream (no pdf-lib parse on untrusted bytes, BLK-009): named osteo-report* first,
capped native inflation → layered reading: report (v3 as is, v2 migrated, else incompatible_version),
envelope metadata tolerant, snapshot/branding/labels strict → archive kept or snapshotRejected (closed reason)
→ rebaseReportOnSheet(report, index, archivedSnapshot) when the loaded sheet differs (unresolved flags, labels kept)
→ 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
Identity (Step 7, docs/development/IDENTITY.md)
@@ -395,9 +403,14 @@ Database (Supabase)
and annotations); no graphic redesign without prior validation
### Schemas
- `packages/domain/src/report/*.ts` are the report data contracts (v3 current, v2 input only); never change
without bumping the version on a breaking change (additive optional fields keep it)
- All user-provided data goes through Zod parse before hitting the store
- 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,
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
- Every report entering the store comes from the core (new report, draft restore, import, reducer outputs);
form values are plain assignments (D-R7)
- Report version 3: zones by `(annotationId, viewId)`, findings by `(findingZoneId, path)`, severities
`mild|moderate|severe`, `sheet` reference; v2 is migrated through `report-migration-map.json`
(`migrateReportV2ToV3`, never throws on content, `unresolved: true` marks what the sheet no longer holds);
@@ -406,7 +419,7 @@ Database (Supabase)
### Stores
- No direct store mutation outside Zustand actions
- No business logic in components — delegate to store actions
- sessionStorage keys: osteo:draft (auto-saved on every change, v3; a v2 draft is migrated and a stale draft rebased on restore once the sheet is loaded) and osteo:archive (the imported archive envelope, written only on import / new report / reset, never on edits)
- sessionStorage keys: osteo:draft (auto-saved on every change, v3; a v2 draft is migrated and a stale draft rebased on restore once the sheet is loaded, by the core) and osteo:archive (the imported archive envelope, written only on import / new report / reset, never on edits); osteo:quarantine:{draft,archive} (an unreadable text set aside, newest only, never dropped) and osteo:quarantine:draft-pre-rebase (the raw draft of a rebase that flagged items)
- localStorage key: osteo:lastPractitioner (practitioner prefill cache)
### PDF
@@ -497,8 +510,10 @@ Database (Supabase)
## Rust by default (rule adopted 2026-10-12, BDR-043)
Study and roadmap: `docs/development/RUST_ARCHITECTURE_REVIEW.md` (awaiting
the owner's validation before any implementation; release 0.2.0 unaffected).
Study and roadmap: `docs/development/RUST_ARCHITECTURE_REVIEW.md` (validated with
the amendments of Annex C). Done: R0, R1 (worker), R2 (domain core used by the app,
`docs/development/RUST.md` §8). Next: R3 (anatomy core), R4 (PDF core), R5
(pipeline); release 0.2.0 unaffected.
- Any logic that can run in Rust with no significant loss (features, UX,
graphics, data compatibility, security, reliability, useful performance,
@@ -554,12 +569,14 @@ the owner's validation before any implementation; release 0.2.0 unaffected).
## Workflow expectations
- Run `pnpm typecheck && pnpm test:run` before every commit.
- Domain schema changes (`packages/domain/src/report/*.ts`) require updating all callers + bumping version if breaking.
- Run `pnpm typecheck && pnpm test:run` before every commit; after any change under `crates/core` or `crates/wasm`,
`pnpm wasm:build` first (the suites refuse a missing or stale module: BUILD_STAMP).
- Contract changes (`crates/core/src/domain`) require the ts-rs types regenerated and committed, all callers updated,
the N-1 reader test green, and a version bump if breaking. `apps/app/src` never imports `@faunosteo/domain` (ESLint).
- 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` — they handle user data; archive readers never drop a schema version (envelope v1, Report v2/v3, sheet document v2).
- 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).
- 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.
- Node 24 / pnpm 10.13.1: `corepack enable` or `corepack pnpm`; never a global install.