docs(docs): R5.7 census, ledger, reproducibility, RUST.md 11.23

CLAUDE.md, WORKSPACE, packages/README, README, sheet model, SUPABASE, TEST_STRATEGY,
PDF-FORMAT and ANNOTATION-RENDERING follow the deletion; RUST.md 11.23 records the census,
counts, the historical TS replay procedure and hashes; CHANGELOG, TODO, R5.7 plan and
contract.
This commit is contained in:
bchanot committed 2026-10-25 04:00:15 +01:00
1 parent 1b359598ab
commit 4e0a6c04d6
14 files changed
+301 -56

No files matched your search

+23 -24
View File
@@ -15,8 +15,8 @@ writes conclusion, and exports an A4 PDF. PDF carries the full JSON state as a n
attachment so importing it restores the session for a follow-up.
SPA deployed via Docker + nginx on Scaleway VPS. Backend foundation on Supabase
(PostgreSQL + Auth + RLS) since Step 3 of the SaaS plan: profiles, platform roles and
audit log exist; Step 4 added the canonical anatomical sheet model (`packages/domain`,
tables `species`, `anatomical_sheets` / `_versions` / `_assets`). Step 5 moved the
audit log exist; Step 4 added the canonical anatomical sheet model (since R2 in
`crates/core/src/domain/sheet`; the TypeScript `packages/domain` left at R5.7), tables `species`, `anatomical_sheets` / `_versions` / `_assets`). Step 5 moved the
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
@@ -40,8 +40,11 @@ Rust R2 moved the application's domain rules into `crates/core` (sheet, report a
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.
pages only (`docs/development/RUST.md` §8). R5 moved the anatomical pipeline (legacy
importer, curation, migration map, review files, seed SQL, upload tool) into the core
(feature `curation`); R5.6 switched the sheet fingerprint to `sha256-rfc8785-validated-v1`;
R5.7 deleted `packages/anatomy` and `packages/domain` (`RUST.md` §11.23, test ledger
`crates/core/tests/curation/LEDGER.tsv`).
MVP species: equine only. Open-source MIT.
---
@@ -74,8 +77,8 @@ MVP species: equine only. Open-source MIT.
## Build commands
pnpm workspace: `apps/app` = the private application, `packages/domain` = pure
Zod domain model (anatomical sheet document), `packages/supabase` = Supabase
pnpm workspace: `apps/app` = the private application, `packages/core-wasm` = the
Rust core in the browser (runtime, generated types, frozen N-1 reader), `packages/supabase` = Supabase
access layer (see `docs/development/WORKSPACE.md`). Every command
below runs from the repository root and delegates to the packages.
@@ -118,9 +121,9 @@ pnpm db:types:check # CI diff
# Reference sheet in the app: the dev server bundles the curated draft; a build does not
pnpm build:preview # SHEET_BUNDLE=draft build (manual validation, preview deployments)
pnpm preview:draft # same, then serves it
pnpm import:equine --check | --out <dir> # since R5.6 the official seed writer: the Rust pipeline (same as `pnpm r5:import-equine`), fingerprint `sha256-rfc8785-validated-v1`; `pnpm import:equine:legacy` = the TypeScript generator (pre-switch convention) until R5.7
pnpm import:equine --check | --out <dir> # since R5.6 the official seed writer: the Rust pipeline (same as `pnpm r5:import-equine`), fingerprint `sha256-rfc8785-validated-v1`; the TypeScript generator left at R5.7 (replayed from a historical revision only, RUST.md §11.23)
pnpm r5:import-equine --check | --out <dir> # the Rust pipeline (R5.2 importer, R5.3 draft, R5.4 review files): compare the 18 generated files with the committed folders (bytes; app drawings under the declared R3 rule), or write <dir>/{legacy-import,draft} into an empty folder; never deletes (scripts/import-equine.sh, first run compiles)
pnpm assets:upload [--check] <seed folder> # R5.5: uploads the sheet drawings of a generated seed folder to the LOCAL stack's private bucket (Rust `upload-sheet-assets`, feature `upload`; SUPABASE_URL local with a port, SUPABASE_SERVICE_ROLE_KEY typed, never printed; no overwrite, confirm after verify; run by hand, scripts/upload-sheet-assets.sh); the TypeScript one is `assets:upload:legacy` until R5.7
pnpm assets:upload [--check] <seed folder> # R5.5: uploads the sheet drawings of a generated seed folder to the LOCAL stack's private bucket (Rust `upload-sheet-assets`, feature `upload`; SUPABASE_URL local with a port, SUPABASE_SERVICE_ROLE_KEY typed, never printed; no overwrite, confirm after verify; run by hand, scripts/upload-sheet-assets.sh)
pnpm e2e:sheet-assets # scripts/sheet-assets-e2e.sh: that tool against the local stack (upload, rerun, anon and wrong key, refused destinations); run by hand
pnpm report:compare <pdf|dir>... # archive check: attachment vs its v3 reading, unresolved items flagged (docs/PDF-FORMAT.md); the core's `report-compare` binary since R4.7 (scripts/report-compare.sh, first run compiles)
@@ -172,7 +175,7 @@ pnpm test # vitest watch — dev loop
Test files live in `apps/app/tests/unit/*.test.ts(x)`; golden fixtures in
`apps/app/tests/fixtures/`. The 612 legacy catalog leaves run through the v2 → v3 migration
in both `packages/anatomy` (against the draft document) and the app (sheet index + PDF roundtrip). Setup: `apps/app/tests/setup.ts` imports
in the core (`crates/core/tests/curation_leaves.rs`, against the draft document) and the app (sheet index + PDF roundtrip). Setup: `apps/app/tests/setup.ts` imports
@testing-library/jest-dom. Suites run on the bundled reference sheet (`tests/helpers/sheet.ts`); frozen v2 fixtures under `tests/fixtures/`.
SQL: `supabase/tests/*.sql` (pgTAP) run by `packages/supabase/tests/db/pgtap.test.ts`
on PGlite (part of `pnpm test:run`) and by `pnpm db:test` on the real stack.
@@ -259,13 +262,7 @@ faunosteo/
├─ eslint.config.js, index.html, package.json (@faunosteo/app)
├─ tsconfig*.json, vite.config.ts, vitest.config.ts
│ (end of apps/app)
├─ 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`: 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
│ (packages/domain and packages/anatomy deleted at R5.7: their sources resolve at 756b7ef, crates/core/tests/curation/{FILES,LEDGER}.tsv)
├─ packages/supabase/ ← @faunosteo/supabase
│ ├─ src/{index,client,database.types,anatomical-sheets,assets}.ts ← typed client, generated types, publish gate, avatar flow (closed AssetFailure kinds)
│ ├─ tests/e2e/avatar-flow.e2e.ts + vitest.e2e.config.ts ← real-stack end-to-end (`pnpm e2e:avatar`), skipped without the stack env
@@ -409,8 +406,8 @@ 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 pipeline until R5, same output), with the attributes listed there
drawn from the document (the Rust core, `crates/core/src/anatomy`, for the canvas since R3, the PDF since R4 and
the pipeline's review drawings since R5), 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`
@@ -421,8 +418,8 @@ 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 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
`packages/domain` was deleted at R5.7; its byte-identical 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);
@@ -494,16 +491,16 @@ Database (Supabase)
- Avatar UI follows the validated mockup: photo in Mon compte (Informations personnelles), sidebar, drawer and top bar
link to Mon compte; JPEG / PNG / WebP only, never SVG; no signed URL for the owner-only avatar (download under RLS).
### Anatomical sheet model (packages/domain + migration 20261008110000)
### Anatomical sheet model (crates/core/src/domain/sheet + migration 20261008110000)
- `docs/development/ANATOMICAL_SHEET_MODEL.md` is the source of truth: document shape, issue codes, tables, RPCs.
- Ids are stable slugs never derived from labels; labels are `{ fr, en }` objects. Annotation → findings is the
explicit `finding_zone_id`; vertebral regions are ordered data with free codes. No label matching at runtime.
- A published version is immutable (trigger, every role). Change = new draft (`create_sheet_draft`) then
`publish_sheet_version`. Integrity rule codes are shared by `validateSheetDocument` (TS) and
`publish_sheet_version`. Integrity rule codes are shared by `validate_sheet_document` (Rust core) and
`private.sheet_document_issues` (SQL); add a rule on both sides and in the spec table.
- Document schema change → bump `SHEET_DOCUMENT_SCHEMA_VERSION`, extend the SQL CHECK on `document_schema_version`.
- Official equine sheet = generated seed `draft/` (`pnpm import:equine --out` into an empty folder, then reviewed and copied; never edit `legacy-import/` or `draft/` by hand;
the golden test fails on drift). Every content change goes through `curation/changes.json` (traced in CHANGELOG.md).
`curation_draft` / `curation_review` fail on drift, `pnpm import:equine --check` lists it). Every content change goes through `curation/changes.json` (traced in CHANGELOG.md).
It is a DRAFT until a platform admin publishes it after business review of `REVIEW-REPORT.md`.
- Sheet SVG bytes live in Storage bucket `anatomical-sheet-assets` as `<sha256>.svg`; uploads are an operator task
(`pnpm assets:upload <seed dir>` with the service key in env), never from the browser.
@@ -529,7 +526,9 @@ Database (Supabase)
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), R3 (anatomy core: SVG reader, layer, composition; editor canvas on it,
RUST.md §9; validated and merged 2026-10-17). Next: R4 (PDF core), R5 (pipeline); release 0.2.0 unaffected.
RUST.md §9; validated and merged 2026-10-17), R4 (PDF core, RUST.md §10; merged 2026-10-21). R5 (pipeline,
RUST.md §11: R5.1 to R5.7, the TypeScript packages deleted) on `feature/rust-r5-pipeline-core`, not merged;
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,