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:
1 parent
7be94d4ce6
commit
8e8c58efca
7 files changed
+306
-76
No files matched your search
@@ -6,6 +6,13 @@ Versions follow [Semantic Versioning](https://semver.org/).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Changed (Rust R2, domain core, 2026-10-14)
|
||||
|
||||
- **The application's domain rules run in Rust** (`crates/core`, through the wasm facade and `@faunosteo/core-wasm`): sheet, report and archive contracts with the Zod semantics reproduced, the 21 sheet integrity rules and the publish check, the sheet index, the v2 → v3 migration, the rebase on the loaded sheet, the sheet snapshot, the layered archive reading, the editor's click chain and reducers, the findings and vertebra rules, report creation and the observation list operations. Consumers switched: the editor, the pickers, the store, the draft restore, the PDF import (after the engine's byte scan) and export (snapshot), the Supabase publish gate (fails closed). The module (372 KB gzip) loads only on the sheet pages; sign-in, the `/app` space and Home never request it. Without `'wasm-unsafe-eval'` in the CSP the editor shows a degraded notice with a retry and leaves the session's draft untouched (DEPLOY.md: set the keyword before deploying an R2 image; R2 images are never built on the VPS).
|
||||
- **Session data never dropped silently**: an unreadable draft or archive is set aside under `osteo:quarantine:*` with a notice; a draft rebased with unresolved items keeps its raw text.
|
||||
- Behaviour differences, declared in `docs/development/RUST.md` §8.7: drafts and attachments written in contract order (values unchanged, the previous build reads them, D-R11); a lone UTF-16 surrogate escape reads as U+FFFD (L1, to confirm); typed errors on inputs the interface never produced.
|
||||
- Proofs: contracts byte-equal to the Zod output on the reference documents, the three archive envelopes frozen before the switch and deep-equal after, 1,000+ cases frozen from the TypeScript, permanent N-1 reader test, generated pgTAP conformance file (real stack 446/446), CSP proof on the real image. No interface, archive format, database or graphic change; release 0.2.0 untouched.
|
||||
|
||||
### Changed (development environment, 2026-10-13)
|
||||
|
||||
- **DEV on the private network** — the owner tests from other devices: the DEV origin (the machine's LAN address, `FAUNOSTEO_DEV_HOST`, detected or set) lives in `scripts/dev-env.sh`; `pnpm dev` serves the app on that origin wired to the local stack, `pnpm dev:offline` keeps the local tool alone; every Supabase CLI call goes through `scripts/supabase.sh` so `config.toml` (API external URL for the mail links, site URL, Studio API URL via `env()`) follows the origin; private-network redirect URLs for the PKCE links. Identity recorded: Faunosteo, https://faunosteo.com; environments DEV / STAGING / PROD and the exposure table in `docs/development/ENVIRONMENTS.md`.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -608,6 +608,13 @@ builds. The procedure below is prepared and documented now; it replaces
|
||||
this way is deployed, after a separate validation**. Until then the live
|
||||
deployment keeps building on the VPS as documented above.
|
||||
|
||||
**From R2 on (`feature/rust-r2-domain-core`), the application image
|
||||
compiles the Rust core** (Dockerfile stage `wasm`: the Rust toolchain and
|
||||
`wasm-bindgen-cli` in a builder stage). Such an image is never built on the
|
||||
VPS (1 vCPU, 1 GB): it is built on the development machine or a runner and
|
||||
pulled by digest, with the CSP of the next section in place first. The live
|
||||
deployment, built from `main` before R2, is not affected.
|
||||
|
||||
1. Build and publish: run the manual workflow `release-images`
|
||||
(`.gitea/workflows/release-images.yml`, `workflow_dispatch`, never on
|
||||
push) on the forge. Prerequisite not met yet: no runner, registry or
|
||||
@@ -634,14 +641,23 @@ working with the read-only token.
|
||||
|
||||
### WebAssembly and the CSP (from R2 on)
|
||||
|
||||
The application does not load the Rust core module before plan R2. When it
|
||||
does, the two `Content-Security-Policy` headers of this file (nginx and
|
||||
Caddy options) must carry `'wasm-unsafe-eval'` in `script-src`:
|
||||
From R2 the application loads the Rust core module in the sheet pages (the
|
||||
editor, the new-report submit, the PDF import). Before an R2 image is
|
||||
deployed, the two `Content-Security-Policy` headers of this file (nginx and
|
||||
Caddy options above) must carry `'wasm-unsafe-eval'` in `script-src`; the
|
||||
examples above still show the header of the live, pre-R2 deployment:
|
||||
|
||||
```text
|
||||
script-src 'self' 'wasm-unsafe-eval';
|
||||
```
|
||||
|
||||
Without the keyword an R2 image stays usable but degraded: the sign-in and
|
||||
account pages work, the editor shows "Le moteur de calcul de Faunosteo n'a
|
||||
pas pu être chargé" with a retry, and the tab's draft is left untouched
|
||||
(proven on the image by `docker/csp-proof/app-image.sh`,
|
||||
`docs/development/RUST.md` §8.5). The keyword adds nothing for a pre-R2
|
||||
image, so it can be set on the proxy before the switch.
|
||||
|
||||
Proven at R0 under the production nginx image and headers with headless
|
||||
Chrome for Testing 156 (`docker/csp-proof/run.sh`, result in
|
||||
`docs/development/RUST.md` §5): with `script-src 'self'` the browser refuses
|
||||
@@ -651,10 +667,10 @@ the module instantiates. `'wasm-unsafe-eval'` allows WebAssembly compilation
|
||||
only, never `eval` or inline scripts (the proof's inline variant was still
|
||||
blocked). Browser floor for the keyword: Chrome 97, Firefox 102, Safari 16
|
||||
(the Vite 7 baseline). The `.wasm` file is served as `application/wasm` by
|
||||
`nginx:1.31-alpine` out of the box; at R2 `docker/nginx.conf` gains
|
||||
`gzip_static on;` for a precompressed `.wasm.gz` (or `gzip_types
|
||||
application/wasm`) and the served, compressed size is what the D-R13 budget
|
||||
counts.
|
||||
`nginx:1.31-alpine` out of the box; since R2 the image precompresses it and
|
||||
`docker/nginx.conf` serves the `.wasm.gz` with `gzip_static on;` (372 KB
|
||||
served for 1.18 MB raw, D-R13 budget 600 KB). A proxy in front must pass
|
||||
`Content-Encoding` through and keep the `application/wasm` type.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+213
-30
@@ -1,13 +1,15 @@
|
||||
# Rust in the Faunosteo monorepo
|
||||
|
||||
Status: plan R0 (foundation, validated 2026-10-13) and R1 (the Step 8 worker,
|
||||
2026-10-13, `feature/step-08-files-foundation`). Rule and roadmap:
|
||||
`RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III boundary
|
||||
rules, Part IV the worker, Part VI phases R0–R5, Annex B R0 scope, Annex C
|
||||
owner amendments). R0 shipped the toolchain, the workspace skeleton, the
|
||||
worker's sandboxed child, the browser module loader and seven experimental
|
||||
proofs; R1 ships the worker's job loop and sweeper for the avatar pipeline
|
||||
(`STORAGE.md` §3). The frontend does not load the browser module before R2.
|
||||
Status: plan R0 (foundation, validated 2026-10-13), R1 (the Step 8 worker,
|
||||
validated 2026-10-13) and R2 (the domain core, delivered 2026-10-14 on
|
||||
`feature/rust-r2-domain-core`, awaiting the owner's validation). Rule and
|
||||
roadmap: `RUST_ARCHITECTURE_REVIEW.md` (rule "Rust by default", Part III
|
||||
boundary rules, Part IV the worker, Part VI phases R0–R5, Annex B R0 scope,
|
||||
Annex C owner amendments). R0 shipped the toolchain, the workspace skeleton,
|
||||
the worker's sandboxed child, the browser module loader and seven
|
||||
experimental proofs; R1 ships the worker's job loop and sweeper for the
|
||||
avatar pipeline (`STORAGE.md` §3); R2 moves the application's domain rules
|
||||
into `crates/core` and switches the application to them (§8).
|
||||
|
||||
## 1. Toolchain: native on the development machine, reproducible in Docker, never on the VPS
|
||||
|
||||
@@ -109,10 +111,10 @@ rustfmt.toml edition 2024, max_width 100
|
||||
clippy.toml disallowed-methods: std::time::*::now, std::fs::*, std::env::var* (the core)
|
||||
deny.toml licences allow-list, bans (duplicates warn, wildcards deny, path deps allowed), sources
|
||||
.cargo/config.toml wasm shadow stack 1 MiB (explicit), TS_RS_EXPORT_DIR = packages/core-wasm/types
|
||||
crates/core faunosteo-core: lib, no I/O (lint), serde + serde_json only
|
||||
crates/core faunosteo-core: lib, no I/O (lint), serde + serde_json + url (Zod's .url())
|
||||
crates/wasm faunosteo-wasm: cdylib facade over core (wasm-bindgen)
|
||||
crates/worker faunosteo-worker: bin + lib (image, libwebp-sys, seccompiler, rlimit)
|
||||
packages/core-wasm loader, generated types (committed), vitest proofs
|
||||
packages/core-wasm runtime (lazy, poison, recovery), Node source, generated types (committed), N-1 reader, tests
|
||||
```
|
||||
|
||||
Lints: `unwrap_used`, `expect_used` and `disallowed_methods` are errors in the
|
||||
@@ -124,23 +126,26 @@ under a 10 s CPU limit.
|
||||
|
||||
### 2.1 Boundary rules in code (review III.3)
|
||||
|
||||
- `faunosteo_core::facade::call(op, json) -> json`: one operation name, one
|
||||
JSON text in, the outcome envelope out (`{"ok":true,"value":…}` or
|
||||
`{"ok":false,"kind":…,"detail":…}`), never a panic on content. R0 ops:
|
||||
`core_version`, `pretty_json`, `sheet_ref`, `report_zone`.
|
||||
- `faunosteo_core::facade::call(op, json) -> json` and
|
||||
`call_with_sheet(sheet, op, json)`: one operation name, one JSON text in,
|
||||
the outcome envelope out (`{"ok":true,"value":…}` or
|
||||
`{"ok":false,"kind":…,"detail":…[, "found":<number>]}`), never a panic on
|
||||
content. The operations of R2 are listed in §8.2 (`crates/core/src/ops.rs`).
|
||||
- `faunosteo_core::json`: `js_number(f64)` prints floats as ECMAScript
|
||||
`Number::toString`; `JsPrettyFormatter` is `serde_json`'s pretty formatter
|
||||
with that rule; `to_js_pretty` and `pretty_js_round_trip` produce
|
||||
`JSON.stringify(v, null, 2)` byte for byte (proof §5.2).
|
||||
- `faunosteo_core::domain::report`: `SheetRef`, `ReportZone`, `Vertebra`,
|
||||
`LateralSide`, `Unresolved`, field order of the Zod schemas, optional
|
||||
fields `skip_serializing_if = "Option::is_none"`, nullable fields plain
|
||||
`Option`, unknown keys ignored where Zod strips them. `cargo test -p
|
||||
faunosteo-core --features ts` writes the TypeScript types to
|
||||
`packages/core-wasm/types` (committed; CI fails on drift).
|
||||
- `packages/core-wasm/src/index.ts`: `loadCore()` instantiates a **fresh**
|
||||
module each time (cache-busting import of the glue), `callCore()` parses
|
||||
the envelope, `isCoreBuilt()` lets the proofs skip when `pkg/` is absent.
|
||||
`Number::toString`; `to_js_pretty` / `to_js_compact` produce
|
||||
`JSON.stringify(v, null, 2)` / `JSON.stringify(v)` byte for byte (proof
|
||||
§5.2). Every facade output goes through them.
|
||||
- `faunosteo_core::domain::js`: the JavaScript and Zod semantics the
|
||||
contracts depend on (`JSON.parse` duplicate keys, lone surrogates → U+FFFD
|
||||
(L1, §8.7), `.int()` as `JsInt`, UTF-16 lengths, the id / region / colour /
|
||||
sha256 / base64 / uuid / URL patterns, optional fields absent and never
|
||||
`null`, nullable fields required). Fields are declared in the Zod schema
|
||||
order (D-R11). `cargo test -p faunosteo-core --features ts` writes the
|
||||
TypeScript types to `packages/core-wasm/types` (committed; the drift gate
|
||||
of `check:all` fails on any change).
|
||||
- `packages/core-wasm`: `CoreRuntime` (browser-safe) and the Node source
|
||||
(`@faunosteo/core-wasm/node`); a fresh instance is a new glue module record
|
||||
(cache-busting import), never the trapped one (§8.3).
|
||||
|
||||
## 3. The worker (R0 sandboxed child, R1 job loop)
|
||||
|
||||
@@ -419,7 +424,8 @@ pnpm rust:builder && pnpm rust:check:docker && pnpm wasm:build:docker # the sa
|
||||
pnpm worker:test # §5.3, §5.4 (tests + derivation in the build log)
|
||||
pnpm worker:image && docker run --rm --read-only --cap-drop ALL faunosteo_worker:dev # §3
|
||||
CHROME=<chromium binary> bash docker/csp-proof/run.sh # §5.5 (playwright-core on NODE_PATH)
|
||||
pnpm check:all # everything above but the CSP proof, in one command
|
||||
CHROME=<chromium> PLAYWRIGHT_NODE_MODULES=<dir> bash docker/csp-proof/app-image.sh # §8.5, the R2 image
|
||||
pnpm check:all # everything above but the CSP proofs, in one command
|
||||
```
|
||||
|
||||
## 7. What stays hypothetical after R0
|
||||
@@ -431,9 +437,9 @@ pnpm check:all # everything above bu
|
||||
bitstream); the shared BuildKit cache mounts of the CI builds (the
|
||||
release workflow already uses its own builder); `actions/*@v4` tags in
|
||||
`ci.yml` (pre-existing practice) to pin by commit at Step 27.
|
||||
- The browser-side fresh-instance mechanism (static glue URL with a
|
||||
cache-busting query under Vite, or a Worker per instance) is designed, not
|
||||
built: R2 builds and tests it.
|
||||
- The browser-side fresh-instance mechanism is built at R2 (§8.3): the glue
|
||||
is a Vite asset imported with a query per instance, one spare record
|
||||
imported in advance.
|
||||
- HTTPS from the worker: R1 links `ureq` with rustls and the bundled
|
||||
`webpki-roots` (distroless has no CA bundle; none is needed), but every
|
||||
run so far targets the local stack over plain HTTP on the Docker network;
|
||||
@@ -444,3 +450,180 @@ pnpm check:all # everything above bu
|
||||
- The allowlist is x86_64; an aarch64 host would need its own derivation
|
||||
(`target_arch` selects the seccomp architecture, the syscall numbers come
|
||||
from `libc`).
|
||||
|
||||
## 8. R2: the domain core in Rust, used by the application (2026-10-14)
|
||||
|
||||
Plan and contract: `.claude/tasks/plans/2026-10-13-rust-r2-domain-core.md`
|
||||
(revision 2 after three plan challenges). The application's domain rules run
|
||||
in `crates/core`, reached through `crates/wasm` and `packages/core-wasm`;
|
||||
React, the DOM, the forms, Zustand and supabase-js stay TypeScript.
|
||||
|
||||
### 8.1 What runs in Rust, and who calls it
|
||||
|
||||
| Former TypeScript | Rust (`crates/core/src`) | Application consumer |
|
||||
|---|---|---|
|
||||
| sheet document schema (Zod, strict) | `domain/sheet/schema.rs` | `SheetHandle` load (`useSheet`), snapshot gate, publish check |
|
||||
| `validateSheetDocument` (21 rules), `isPublishable`, `createEmptySheetDocument` | `domain/sheet/{validate,check,create}.rs` | `sheet.check` → `publishSheetVersion` (packages/supabase), snapshot integrity |
|
||||
| `buildSheetIndex` (closures over Maps) | `domain/sheet/{index,index_data}.rs`, `SheetHandle` | `useSheet` → `SheetIndex` (precomputed tables, no call in a render) |
|
||||
| report v3 / v2 / identity / migration map (Zod) | `domain/report/{v3,v2,identity,migration_map}.rs` | every op that takes or returns a report |
|
||||
| `migrateReportV2ToV3`, `readReportDocument` | `domain/report/read.rs` | draft restore, import |
|
||||
| `rebaseReportOnSheet` (gated, D-R12) | `domain/report/rebase.rs` | draft restore, import |
|
||||
| snapshot / branding / labels / envelope schemas, `buildSheetSnapshot`, `assertSnapshot`, `readArchiveDocument` (gated, D-R12) | `domain/archive/*` | export (`archive.snapshot`), import (`archive.import`), draft restore (archive kept beside the draft) |
|
||||
| `services/zoneInteraction.ts` (click decision, 7 reducers, `collectVertebrae`, `syncVertebrae`) | `domain/editor/zone.rs` | `EditorRoute` click chain, `ObservationPickers`, zone chips |
|
||||
| `FindingsTreePicker.toggleLeaf` (Finding builder) | `domain/editor/finding.rs` | `ObservationCard` → findings picker |
|
||||
| `VertebraPicker` toggle / all / none | `domain/editor/vertebra.rs` | `VertebraPicker` tap handlers |
|
||||
| store `newReport`, `emptyObservation`, add / remove / move | `domain/editor/report_ops.rs` | `reportStore` actions (answer `{ ok }`) |
|
||||
| `persistence` draft / archive parsing | `domain/session.rs` (`restore_draft`) | `reportStore.restoreDraft` (quarantine on content kinds) |
|
||||
| engine `readReportArchive` (layered part) | `domain/session.rs` (`import_archive`) | `HomeRoute` import after the engine's byte scan |
|
||||
|
||||
### 8.2 Facade operations (`crates/core/src/ops.rs`, `facade.rs`)
|
||||
|
||||
Free (`call`): `sheet.check`, `report.new`, `report.add_observation`,
|
||||
`report.remove_observation`, `report.move_observation`, `vertebra.select`;
|
||||
R0 proofs kept: `core_version`, `pretty_json`, `sheet_ref`, `report_zone`.
|
||||
On the session's sheet (`SheetHandle.call`): `index_data`, `zone.click`,
|
||||
`zone.add_sides`, `zone.remove_at`, `vertebra.initial`, `vertebra.sync`,
|
||||
`finding.toggle`, `draft.restore`, `archive.import`, `archive.snapshot`.
|
||||
Closed failure kinds: `invalid_json`, `invalid_shape`, `unknown_op`,
|
||||
`internal`, `invalid_sheet` (handle), `invalid` / `unsupported_version` /
|
||||
`rebase_failed` (restore), `incompatible_version` (with `found`) /
|
||||
`no_attachment` / `invalid` (import), `unknown_annotation`, `unknown_zone`,
|
||||
`unknown_node`, `invalid_index`, `invalid_count` (editor); the runtime adds
|
||||
`core_unavailable`. Input contracts are exported as TypeScript types.
|
||||
|
||||
### 8.3 Runtime in the browser (`packages/core-wasm/src/runtime.ts`, `apps/app/src/core/`)
|
||||
|
||||
- Lazy: the glue (10 KB) and the module are Vite assets (`?url`), never in
|
||||
a route chunk; nothing is fetched before `ready()`. Callers: the editor
|
||||
(`useSheet`), the new-report submit, the PDF import. `/login`, `/app/*`,
|
||||
Mon compte and Home never request it (proven, §8.5); Home and `/new` read
|
||||
the sheet availability from the bundle alone.
|
||||
- Synchronous calls once ready. A `WebAssembly.RuntimeError` poisons the
|
||||
instance: the call answers `internal`, the instance is dropped, a fresh one
|
||||
is created from the compiled module kept in memory and a glue record
|
||||
imported in advance (no network needed), at most 3 times per page; calls
|
||||
made meanwhile answer `core_unavailable`. Sheet handles carry the instance
|
||||
generation and are rebuilt from the retained payload, never called on a
|
||||
dropped instance.
|
||||
- A load failure (CSP, network, old browser) gives `core_unavailable`; the
|
||||
editor and the new-report page show the notice with "Réessayer" (the retry
|
||||
clears the runtime, `useSheet` and provider caches), never redirect, never
|
||||
read or write the draft.
|
||||
- Two builds: `pkg/` ships (no trap export, checked by `scripts/wasm-build.sh`
|
||||
and a test), `pkg-proofs/` carries the trap exports for the tests. Both
|
||||
carry `BUILD_STAMP` (hash of the Rust sources); the vitest global setup of
|
||||
`core-wasm`, `app` and `supabase` refuses to run on a missing or stale
|
||||
module (`pnpm wasm:build` first).
|
||||
|
||||
### 8.4 TypeScript deleted, kept, frozen (census)
|
||||
|
||||
- Deleted at R2: `apps/app/src/services/zoneInteraction.ts` and its suite
|
||||
(13 cases ported to `crates/core/tests/editor_rules.rs`), the Finding
|
||||
builder of `FindingsTreePicker`, the selection rules of `VertebraPicker`,
|
||||
the store's report construction and list rules, the Zod parsing in
|
||||
`persistence.ts` and `sheets/provider.ts`, the domain re-exports of
|
||||
`services/sheetIndex.ts`, `hydrateReport`, the publish gate's
|
||||
`assertPublishable` call.
|
||||
- Kept TypeScript, each with its constraint (review II.2 class C): display
|
||||
helpers over core data (`zoneLabel`, `describeZone`, `zoneTrees`,
|
||||
`unresolvedFindings`, the findings picker's `matches` / `isLeafSelected` /
|
||||
`countSelectedUnder`, the vertebra grid extent and chip state, import
|
||||
message lines, `isIdentityComplete`, `pickLabel` = `pickLocaleLabel`);
|
||||
form glue (D-R7: identity, texts, comment, severity and free-findings
|
||||
assignments, `FreeTextFindingInput` trimming, the practitioner prefill
|
||||
schema of `practitionerCache.ts`); storage adapters (`persistence.ts`,
|
||||
quarantine writes); `isObservable` (a type guard); the `SheetIndex` class
|
||||
(reads precomputed tables only); the runtime and its sources (Vite asset
|
||||
URLs, dynamic import).
|
||||
- Frozen TypeScript, still used, never extended: `packages/domain` (PDF
|
||||
engine and `apps/app/scripts/compare-reports.ts` until R4, pipeline until
|
||||
R5), `packages/pdf` (byte scan and writer, R4), `packages/anatomy/render`
|
||||
(canvas and engine, R3). The `report:compare` CLI reads the sheet with
|
||||
the frozen domain (`apps/app/scripts/compare/sheet.ts`).
|
||||
- Census: `grep -rn "@faunosteo/domain" apps/app/src` returns nothing,
|
||||
enforced by ESLint (`no-restricted-imports` on `apps/app/src`).
|
||||
|
||||
### 8.5 Proofs and tests (2026-10-14)
|
||||
|
||||
- Cargo: 135 core tests (contracts byte-equal to the Zod output on the
|
||||
curated and legacy sheets, the demo report and the three frozen archive
|
||||
envelopes; the ported domain suites; 49 editor cases, 84 report and
|
||||
archive cases and 765 Zod verdicts frozen from the TypeScript; 26
|
||||
conformance fixtures; the 612 legacy leaves), 32 wasm + worker unit tests.
|
||||
- Node: 906 tests (`app` 313 on the real core, `core-wasm` 25 incl. the
|
||||
runtime, trap, size and measurement tests, `supabase` 39 incl. the publish
|
||||
gate on the real core, `domain` 262 incl. the oracle generators, `pdf`
|
||||
137, `anatomy` 130); the 39 step6 goldens and the seed golden unchanged.
|
||||
- SQL: `supabase/tests/011_sheet_conformance.sql` generated from the
|
||||
fixtures (cargo drift test), PGlite 12/12 files, real stack 446/446.
|
||||
- N-1: the Zod schemas of develop 1a7ee7d (`packages/core-wasm/tests/n-1`)
|
||||
parse every draft and archive the core-fed application writes; the three
|
||||
frozen envelopes are deep-equal to the R2 exports.
|
||||
- CSP on the real image (`docker/csp-proof/app-image.sh`, Chrome for Testing
|
||||
156, DEPLOY.md header): with `'wasm-unsafe-eval'` a report is created and a
|
||||
zone click is applied by the core with no script or wasm violation; without
|
||||
it the browser refuses the module (`script-src wasm-eval`), the editor
|
||||
shows the notice, stays on `/editor` and leaves the draft byte-identical;
|
||||
`/login`, `/app/account` and `/` request neither the glue nor the module
|
||||
(15/15). Recovery after a forced trap checked in the browser on the dev
|
||||
server and the production build; real traps on the proofs build in Node.
|
||||
- `pnpm check:all`: green in 2 min 17 s.
|
||||
|
||||
### 8.6 Measurements (development machine, Node 24, Chrome 156)
|
||||
|
||||
| Measure | Value |
|
||||
|---|---|
|
||||
| shipped module | 1,180,153 B raw (image) / 1,180,281 B (native), **372,275 B served gzip** (budget 600 KB) |
|
||||
| glue | 10,171 B |
|
||||
| load (compile + instantiate) | 8 ms |
|
||||
| sheet handle + index data (bundle 0.5 MB) | 22 ms (TypeScript parse + index on the same input: 12 ms) |
|
||||
| `zone.click` | 0.04 ms |
|
||||
| `draft.restore` (demo report) | 0.26 ms |
|
||||
| `archive.import` (demo envelope, 184 KiB) | 2.6 ms (TypeScript layered read, without rebase: 1.0 ms) |
|
||||
| `archive.snapshot` | 0.4 ms |
|
||||
| linear memory after the editor path | 4.0 MiB |
|
||||
| app image | 104 MB (wasm stage: the Rust toolchain stays in the builder) |
|
||||
|
||||
Pages without the core load nothing more than before R2; the sheet pages
|
||||
fetch 382 KB more (glue + gzip module) once per session.
|
||||
|
||||
### 8.7 Behaviour differences (declared)
|
||||
|
||||
1. **L1**: a lone UTF-16 surrogate escape in a draft or an attachment reads
|
||||
as U+FFFD instead of being kept (TypeScript kept it, Rust strings cannot
|
||||
hold it). Owner confirmation requested.
|
||||
2. Drafts and the attachment's report are written in contract order instead
|
||||
of insertion order (D-R11); values unchanged, the N-1 reader parses them.
|
||||
3. An unreadable draft or archive is set aside under `osteo:quarantine:*`
|
||||
with the `editor.draft_quarantined` alert, instead of being dropped
|
||||
silently; a draft rebased with unresolved items keeps its raw text under
|
||||
`osteo:quarantine:draft-pre-rebase`.
|
||||
4. A core that cannot load leaves the editor on the degraded notice
|
||||
(before R2 a failed sheet chunk left it on "loading").
|
||||
5. Home and `/new` no longer load the sheet into memory on mount.
|
||||
6. Inputs the interface never produced get typed errors where the
|
||||
TypeScript would throw or corrupt a list (`invalid_index` on a move past
|
||||
the end, `invalid_count` beyond 65,535 vertebrae, `unknown_*`).
|
||||
7. A click on an existing spine zone no longer writes an identical
|
||||
observation back (the value is the same).
|
||||
8. The publish gate throws `SheetPublishError` with closed kinds
|
||||
(`invalid_shape`, `not_publishable` with the same message as before,
|
||||
`validator_unavailable`), never a raw ZodError.
|
||||
9. An unreadable draft that cannot be set aside (storage full) keeps the
|
||||
editor on the degraded notice, whose text speaks of the engine: wording to
|
||||
revisit if the case matters.
|
||||
|
||||
### 8.8 Residual risks
|
||||
|
||||
- The import reads up to the 16 MiB attachment cap inside the long-lived
|
||||
instance (linear memory never shrinks) until R4 moves the reader into a
|
||||
terminated Web Worker.
|
||||
- No React error boundary: every core entry point catches, but an uncaught
|
||||
error elsewhere still blanks the page (unchanged since before R2).
|
||||
- The CSP proof runs Chromium only (no Firefox or WebKit build on this
|
||||
machine): the owner's manual run of the image on other browsers and the
|
||||
phone covers Safari and Firefox.
|
||||
- The module grows with each phase (372 KB of the 600 KB budget at R2; the
|
||||
`url` crate's IDNA tables are part of it): R3/R4 must keep measuring.
|
||||
- The documented CSP refuses the footer's external credit logo
|
||||
(`img-src`), an older matter seen by the proof.
|
||||
@@ -18,7 +18,10 @@ Status: Step 0 deliverable, 2026-10-08. Current state: 32 files under
|
||||
| PDF regression | vitest golden tests: text extraction of generated PDFs, attachment roundtrip, raster hash on fixed inputs | `packages/pdf/tests` | CI |
|
||||
| SQL/TS contract | generated types diff check | CI | every PR touching `supabase/` |
|
||||
| Rust core and facade | `cargo test` (unit + fixture tests reading the repository JSON in place), `clippy -D warnings`, `cargo deny`; ts-rs types drift check | `crates/*`, `pnpm rust:check` (native, `scripts/rust-check.sh`; same file in the builder image), `pnpm check:all` | before every Rust commit and every merge; CI job `rust` prepared, no runner yet |
|
||||
| Rust/TS contract | vitest proofs on the built module: byte equality with `JSON.stringify(…, null, 2)` on the real documents, optional/nullable shape read by the current Zod schemas, panic and stack traps, served size budget | `packages/core-wasm/tests` (skipped with a notice when `pkg/` is absent) | `pnpm check:all` (after the native `wasm:build`); CI `check` prepared |
|
||||
| Rust/TS contract | vitest on the built module: byte equality with `JSON.stringify(…, null, 2)` on the real documents, ts-rs types against the Zod output types, the runtime (lazy load, trap → poison → offline re-instantiation, handle rebuild, cap, retry), panic and stack traps on `pkg-proofs`, served size budget and measurements | `packages/core-wasm/tests` (refused, never skipped, when `pkg/` or `pkg-proofs/` is missing or stale) | `pnpm check:all` (after the native `wasm:build`); CI `check` prepared |
|
||||
| Freeze-then-switch oracles (R2) | outputs of the TypeScript frozen before the switch and checked by cargo: Zod output of the reference documents (byte-equal), 84 report / archive cases, 765 Zod verdicts, 49 editor cases, 26 sheet conformance fixtures (also inlined into the generated pgTAP `011`, drift-checked), the three archive envelopes (deep-equal through the app path) | `crates/core/tests/{oracles,conformance,fixtures}`, generators in `packages/domain/tests/r2-*.test.ts` and `apps/app/tests/unit/archive.envelopes.test.ts` (`MAKE_R2_ORACLES` / `MAKE_R2_FREEZE`, never regenerated without an owner decision) | every Rust commit (`pnpm rust:check`), `pnpm check:all` |
|
||||
| N-1 reader (permanent) | every draft and archive the core-fed application writes parses with the Zod schemas of the last TypeScript build (`packages/core-wasm/tests/n-1`, develop 1a7ee7d) | `apps/app/tests/unit/n-1.reader.test.ts`, `archive.envelopes.test.ts` | every commit (`pnpm test:run`) |
|
||||
| CSP on the image (R2) | the real app image behind the DEPLOY.md CSP in headless Chromium: with `'wasm-unsafe-eval'` the core runs the editor path, without it the degraded state and an untouched draft; no module request on `/login`, `/app/account`, `/` | `docker/csp-proof/app-image.sh` | before a merge touching the core loading or the image; manual (needs Chromium) |
|
||||
| Worker sandbox | integration tests against the musl binary that ships: fixture corpus through the full sandbox, refusals, SIGSYS on a denied syscall, output cap, `RLIMIT_AS` abort, `RLIMIT_CPU`, deadline; seccomp allowlist derived by `strace` and compared | `crates/worker/tests/sandbox.rs`, Dockerfile stage `test` (`pnpm worker:test`, Docker only, never native) | every `crates/worker` commit, `pnpm check:all`; CI `docker` job prepared |
|
||||
| Worker job loop | native unit tests on a fake backend and a fake decoder: call order claim → download → decode → upload → commit → purge, every child outcome mapped to a closed code, no deletion on a refused commit, lease left on transport failures, sweeper targets and acks, key validation, config and secret redaction | `crates/worker/tests/job_loop.rs`, `crates/worker/src/*` unit tests (`pnpm rust:check`) | every Rust commit |
|
||||
| Files e2e (real stack) | the worker container against the local Supabase stack: clean upload and owner-only download (Bob, anon, quarantine, direct final-key write refused), replacement and purge after the grace (queue clock shifted through psql), late signed-upload bytes swept, hostile uploads rejected with closed codes, removal and drained queue | `packages/supabase/tests/e2e/avatar-flow.e2e.ts` (`pnpm e2e:avatar`, `scripts/avatar-e2e.sh`) | every Storage, worker or avatar change; not in `check:all` (needs the stack) |
|
||||
|
||||
@@ -43,8 +43,10 @@ root with `crates/core` (library), `crates/wasm` (browser facade, built into
|
||||
runs on the native toolchain of the development machine (`pnpm rust:check`,
|
||||
`pnpm wasm:build`; user-level rustup, channel of `rust-toolchain.toml`) or,
|
||||
for a reproducible run, through the builder image (`:docker` variants); the
|
||||
pnpm workspace gains `packages/core-wasm` (loader, generated types, proofs),
|
||||
whose tests skip with a notice when the module has not been built.
|
||||
pnpm workspace gains `packages/core-wasm` (runtime, generated types, the N-1
|
||||
reader, tests). Since R2 the application depends on it at runtime (the sheet
|
||||
pages load the module lazily) and the `core-wasm`, `app` and `supabase`
|
||||
suites refuse to run without a fresh `pnpm wasm:build` (BUILD_STAMP).
|
||||
| `supabase/` | migrations, functions, seed, tests | plan Step 3 |
|
||||
|
||||
## 2. Why this layout now
|
||||
|
||||
+7
-5
@@ -13,12 +13,14 @@ Planned packages and the step that creates each one:
|
||||
| `@faunosteo/pdf` | browser-free PDF engine (**created**, Step 6): report archive export from explicit inputs (report, sheet snapshot, branding, labels, rasterizer), layered archive reading, SVG sanitiser, page renderers | Step 6 (PDF archives) |
|
||||
| `@faunosteo/i18n` | FR/EN dictionaries (no React) + `useT` | first second consumer (public-web or worker) |
|
||||
| `@faunosteo/supabase` | browser client factory, generated database types, PGlite harness running the pgTAP suite, sheet publish gate | **created**, Step 3 |
|
||||
| `@faunosteo/core-wasm` | loader of the Rust core compiled to WebAssembly (`pkg/` built by `pnpm wasm:build`, git-ignored), TypeScript types of the contracts generated by ts-rs (committed), the R0 proofs (panic and stack traps, JSON.stringify parity, Zod readers, size budget) | **created**, R0 (Rust review) |
|
||||
| `@faunosteo/core-wasm` | the Rust core compiled to WebAssembly: `CoreRuntime` (lazy load, poison on a trap, offline re-instantiation, sheet handles per instance), Node source, `pkg/` shipped and `pkg-proofs/` (built by `pnpm wasm:build`, git-ignored, BUILD_STAMP), TypeScript types of the contracts generated by ts-rs (committed), the frozen N-1 Zod reader (`./n-1`), the trap, size and measurement tests | **created**, R0; runtime and app consumers R2 |
|
||||
|
||||
From R2 on, the Rust core (`crates/core`) replaces the TypeScript business
|
||||
logic of `domain`, `anatomy` and `pdf` phase by phase
|
||||
(`docs/development/RUST_ARCHITECTURE_REVIEW.md` Part VI); each TypeScript
|
||||
package is deleted in the phase that switches its last consumer.
|
||||
Since R2 the Rust core (`crates/core`) holds the business logic `domain` held
|
||||
for the application (`docs/development/RUST.md` §8); `domain` stays frozen
|
||||
for the PDF engine, the pipeline and the compare CLI. `anatomy` and `pdf`
|
||||
follow at R3 and R4 (`docs/development/RUST_ARCHITECTURE_REVIEW.md` Part
|
||||
VI); each TypeScript package is deleted in the phase that switches its last
|
||||
consumer (`domain` and `anatomy` at R5, `pdf` at R4).
|
||||
| `@faunosteo/config` | runtime config resolution shared by app, public-web, worker | with public-web |
|
||||
| `@faunosteo/ui` | UI primitives and design tokens | only when public-web reuses them |
|
||||
|
||||
|
||||
Reference in new issue
Block a user