docs(docs): RUST.md §11.12-11.13 (R5.3 draft port, parity, declared differences, gates, checkpoint), CHANGELOG, CLAUDE.md commands

This commit is contained in:
bchanot committed 2026-10-23 00:11:06 +02:00
1 parent e0f149b28a
commit 94280a4c56
3 files changed
+127 -4

No files matched your search

+4
View File
@@ -6,6 +6,10 @@ Versions follow [Semantic Versioning](https://semver.org/).
## [Unreleased]
### Changed (2026-10-22, Rust R5.3: the curated draft in Rust)
- The draft side of the anatomical pipeline runs in Rust behind the core's `curation` feature (`crates/core/src/curation/draft`): the authored changeset and references files parsed strictly, the six ops of a change applied on the plain JSON document with their records, the review rule of levels B and C, the shape and integrity gate of the R2 core, the report migration map, the document statistics and the seed SQL. `pnpm r5:import-equine --check` reproduces `legacy-import/` and the R5.3 files of `draft/` (`document.json`, `assets.json`, `sheet-ref.json`, `report-migration-map.json`, `equine_draft.sql`, the frozen `assets/horse.svg`) byte for byte, 12 files, 0 differences; `pnpm r5:import-equine --out <dir>` writes both folders into an empty folder and never deletes anything. The review drawings, `CHANGELOG.md` and `REVIEW-REPORT.md` of the draft stay with the TypeScript until R5.4; `pnpm import:equine` and the seed are unchanged; `documentSha256` stays `27c7383c…2660` until R5.6 (`docs/development/RUST.md` §11.12).
### Changed (2026-10-22, Rust R5.1b and R5.2)
- The core prints an exact decimal tie as JavaScript does (`840.1692504882812`, round half to even), its digits now from `zmij`, the formatter serde_json already used; no historical output carried such a value, so no oracle, golden or PDF digest changed (`docs/development/RUST.md` §11.9).
+4 -3
View File
@@ -118,7 +118,8 @@ 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 # regenerate legacy-import/ and draft/ (document, migration map, review drawings)
pnpm import:equine # regenerate legacy-import/ and draft/ (document, migration map, review drawings): the TypeScript writer of the seed until the R5 switch
pnpm r5:import-equine --check | --out <dir> # the Rust pipeline (R5.2 importer, R5.3 draft): compare with the committed folders, or write <dir>/{legacy-import,draft} into an empty folder; never deletes (scripts/import-equine.sh, first run compiles)
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)
# Rust (docs/development/RUST.md) — native toolchain (user-level rustup, channel of rust-toolchain.toml) first
@@ -279,10 +280,10 @@ faunosteo/
├─ packages/README.md ← shared packages index
├─ packages/core-wasm/ ← @faunosteo/core-wasm: CoreRuntime (lazy, poison, recovery) + CoreExportSession (R4.6) + 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: domain/{js,sheet,report,archive,editor,session} (contracts and rules), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), pdf/{read,json_js,import,write,compare} (R4: reader, writer and session, the archive check tool behind feature `cli`), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing), bin/report_compare.rs (`pnpm report:compare`, the one file allowed std::fs); tests/{oracles,conformance,fixtures,pdf/LEDGER.tsv} frozen from the TypeScript (oracles/r3, oracles/r4, fixtures/svg/hostile); no I/O, no clock (lint-enforced)
│ ├─ core/ ← faunosteo-core: domain/{js,sheet,report,archive,editor,session} (contracts and rules), anatomy/{svg/{prescan,tree,sanitize,refs,number,serialize},layer,compose} (R3: the one SVG reader, the layer, canvas + highlight composition), pdf/{read,json_js,import,write,compare} (R4: reader, writer and session, the archive check tool behind feature `cli`), ops.rs + facade.rs (`call`, `call_with_sheet`), json (JS number printing), curation/{text,ids,prettier_json,markdown,legacy/*,draft/*} (R5, feature `curation`: Prettier layout, the legacy importer, the changeset applier, migration map, stats, seed SQL), bin/report_compare.rs (`pnpm report:compare`) + bin/import_equine.rs (`pnpm r5:import-equine`, the two files allowed std::fs); tests/{oracles,conformance,fixtures,pdf/LEDGER.tsv} frozen from the TypeScript (oracles/r3, oracles/r4, fixtures/svg/hostile); 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,report-compare}.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, the archive check tool (`pnpm report:compare`)
├─ scripts/{rust-env,rust-check,wasm-build,check-all,avatar-e2e,report-compare,import-equine}.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, the archive check tool (`pnpm report:compare`), the Rust pipeline (`pnpm r5:import-equine`)
├─ 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 proofs (R0 module, R2 app image: app-image.sh)
+119 -1
View File
@@ -2562,7 +2562,7 @@ finish` on `feature/rust-r4-pdf-core` (no-ff into develop, branch
deleted local and remote), recorded in `.claude/memory/journal.md`.
Release 0.2.0, faunosteo.com and R5 untouched.
## 11. R5: the anatomical pipeline in Rust (R5.1 freeze and study, 2026-10-22)
## 11. R5: the anatomical pipeline in Rust (2026-10-22: R5.1 freeze and study, R5.1b, R5.2 importer, R5.3 draft)
Plan: `.claude/tasks/plans/2026-10-22-rust-r5-pipeline-core.md`. Branch
`feature/rust-r5-pipeline-core`, cut from develop 9c0117a (R4 merged). The
@@ -2876,3 +2876,121 @@ same inputs (`curation/changes.json`, `references.json`) and its oracles are fro
byte for byte except `sheet-ref.json`'s fingerprint, which stays `27c7383c…2660` until
R5.6); the cleaned `horse.svg` is kept as frozen bytes (owner decision), so R5.3 reads it
instead of re-cleaning the legacy drawing; the review drawings (xmldom bytes) wait for R5.4.
### 11.12 R5.3: the curated draft in Rust (2026-10-22)
Owner go « Validation R5.1b / R5.2 et autorisation R5.3 » (2026-10-22): `pnpm r5:import-equine`
names the Rust binary and forwards its arguments, `pnpm import:equine` keeps writing the seed
until the switch; no fingerprint change; the cleaned `horse.svg` is read as frozen bytes, never
re-cleaned; the review drawings and the two Markdown reports are R5.4. Contract
`.claude/tasks/contracts/2026-10-22-rust-r5-draft.md`.
`crates/core/src/curation/draft` (2,718 lines, feature `curation`):
| Module | Ports |
|---|---|
| `schema.rs` | `ChangesetSchema`, `ReferencesFileSchema`: strict objects, optional keys `.optional()` (absent accepted, `null` refused), the `CHG-\d{3,}` id, `priority` defaulted to `medium`, the level C question, duplicate change and reference ids refused; the `op` discriminator read first, then the variant parsed strictly; re-emitted in the Zod shape order (`question` before `priority`, options absent) |
| `targets.rs` | the target grammar, resolution on the plain JSON document (a located item is a path of keys and indices, resolved again at each use where the TypeScript held object references), `zoneFindings`, `allFindings`, `findingScope`, `childList` (a lean leaf gets `children: []` appended on demand) |
| `fields.rs` | the settable table per item kind, dot paths, `readField` / `writeField` (missing intermediate objects created) |
| `records.rs` | `ChangeRecord`, the touch marks (`"\0touched"`: a transient key holding the first-touch order, removed at the end of each change and never written to a record), `isDeepStrictEqual` on JSON values (`Object.is` on numbers), `String(value)` |
| `ops.rs`, `rename.rs` | the six ops with their checks and messages, the rename cascade (one record per rewrite; a reference rename rewrites the citations) |
| `apply.rs` | `applyChangeset`: references replaced first, every op refused with the change id and op index, the review rule (touched findings and annotations of a B or C change set `to_confirm` in first-touch order, items already `to_confirm` or gone skipped), then the R2 strict parse (`AnatomicalSheetDocument`) and `validate_sheet_document` (errors refuse, warnings returned) |
| `migration_map.rs` | `buildReportMigrationMap`: the 792 legacy paths replayed through the rename, remove and move records, zone renames, annotation and view renames, the final-paths check, unique re-homing, the five stats; `Object.keys` order through `js_object` |
| `stats.rs` | `documentStats`: 17 fields in the TypeScript order, the fixed-key counters extended by unlisted values |
| `seed.rs` | `renderDraftSeedSql`: header, sheet insert, asset inserts, `insert_sheet_draft`, converging update, the dollar-tag refusal, `trimEnd` |
| `pipeline.rs` | `buildEquineDraft` (CHG-000 from the frozen asset's sha256, byte size and uuid, the head view box parsed from the legacy SVG; the reserved id refused), `renderDraftArtifacts` for the R5.3 files (`document.json`, `assets.json`, `sheet-ref.json` with `document_sha256` = sha256 of the `document.json` bytes, `report-migration-map.json`, `equine_draft.sql`), `parseViewBox` |
| `bin/import_equine.rs` | both folders; `--check` compares the produced files with the committed seed and lists the six R5.4 files of the draft as pending (`shortcut:` comment, removed at R5.4); `--out <dir>` writes `<dir>/legacy-import` and `<dir>/draft` into a destination that is absent or an empty folder, refuses an empty path, a symbolic link, a path that is not a folder, a folder holding any file; an absent destination is created before any write (nothing can appear between the check and the writes) and the files go to its canonical path, which the success line prints (a symbolic link among the parent folders is visible there); a relative path is typed from `INIT_CWD` when absolute, else the current folder; nothing is ever deleted |
Parity, every expectation written by the TypeScript (`tests/curation_draft.rs`, 8 tests):
- the five R5.3 text files of the committed `draft/` byte for byte, the frozen `horse.svg`
described by its sha256, size and asset id; `pnpm r5:import-equine --check`: 12 files, 0
differences; `--out` then `diff -r`: `legacy-import/` identical, `draft/` identical but
for the six R5.4 files;
- `sheet-ref.json`'s `document_sha256` equals the sha256 of the produced `document.json`
and the historical `27c7383c…2660` (by construction: same bytes, same rule);
- the draft section of `oracles/r5/pipeline.json`: sheetId, the 46 change summaries (CHG-000
included), the asset, `statsBefore` and `statsAfter`, the empty issue list, the migration
stats (792 nodes: 571 identical, 180 remapped, 7 re-homed, 34 removed) and the 825 records
one by one under the JavaScript compact print; two runs byte-equal;
- the 612 legacy leaves through the core's `read_report_document` on the produced map: 442
identical, 141 moved, 29 removed, every resolved leaf a leaf of the produced document, the
29 flagged paths exactly those the map sends to null, the FR snapshots kept;
- 58 synthetic changesets on the mini sheet (`oracles/r5/curation-synthetic.json`,
generator `packages/anatomy/tests/r5.curation-synthetic-oracles.test.ts`): 9 accepted
cases (every op kind, numeric and anchored positions, subtree scopes with skipped equal
values, the review rule on levels A, B and C, the five rename cascades and a reference
rename, re-homing, two chained changes) byte for byte on the formatted document, the
records, the stats, the migration map and the seed SQL; 48 refusals (19 schema, `null`
on `scope`, `position` and `field` included, 29 applier, integrity and shape gates
included) refused alike; 5 references files refused
alike; one declared difference below.
Differences declared (none reachable by the committed files, since the folders are
reproduced byte for byte):
| Input | TypeScript | Rust |
|---|---|---|
| a `set` op without `value` | `z.unknown()` accepted the missing key; the op wrote `undefined` and `JSON.stringify` dropped the field (synthetic case `declared-set-without-value-drops-key`: `description: {}`) | refused at parse (`missing field value`) |
| a `position` written as `1.0` or `-0` | accepted (`Number.isInteger`) | accepted alike (parsed as a JavaScript number, then integral and non-negative) |
| a lone surrogate escape (`"\ud800"`) in any string of the two files | `JSON.parse` kept it | refused (the core's L1 rule: no lone surrogate is ever read) |
| nesting deeper than 128 levels (an `add` of a 70-level finding chain) | accepted | refused at parse (serde_json's depth limit, kept as a resource bound) |
| a number beyond the double range (`1e400`) in a value a later op overwrites or removes | `JSON.parse` read Infinity, the value was discarded, the change accepted (a surviving value is refused by both at the gate) | refused at parse (serde_json's range check) |
| a `set` field path through an inherited `Object.prototype` member (`name.constructor`) whose parent a later op replaces | `structuredClone` of the function read there threw, change refused | the member is a plain missing key: accepted (a surviving key is refused by both at the gate) |
| a `set` field path ending in `__proto__` (`name.__proto__`) | the prototype setter swallowed the write: change accepted, document unchanged, one record | the key is written and the strict document gate refuses it (the R5.2 family: a name of `Object.prototype` is a plain key) |
| an authored key starting with NUL (`"\u0000touched"`) in a value | refused at the strict document gate when the value reaches the document, accepted when a later op overwrites or removes it | refused at parse (`reserved key`): the prefix is reserved for the applier's transient touch marks |
Observation, not a difference (reproduced as is): `applyRecord` of the migration map reads
`record.op` whatever `record.target` is, so a cascade record of a view, zone, category or
region rename whose target is an annotation of the legacy id map would be replayed as an
annotation rename, and a reference rename cascading into a finding's citations would be
replayed as a finding rename. The committed changeset renames findings only (33) and no
reference, so neither path runs; a fix would be a declared behaviour change of both
implementations, the owner's call.
Kept as the TypeScript: invalid UTF-8 in the two curation files becomes U+FFFD
(`readFile(path, 'utf8')`, as R5.2 kept for the catalog); a repeated key in either file keeps its first position and its last
value (`JSON.parse`, through the core's `parse_json`; tested on a change and a reference);
ids compared as strings (`entry[key] === id`), a non-object entry
never matches; `String(x)` of a missing id is `"undefined"`; the error messages of the ops
(`unknown target "…" (no "…")`, `position N out of range`, …) are the TypeScript ones with
the change id and op index prefixed.
Tests: `cargo test -p faunosteo-core --features curation` (draft 8, importer 5, formatting
6, plus the crate's suites); anatomy 142 (the generator added); `pnpm rust:check` green.
Gates: security auditor PASS (semgrep 0 findings, 6 LOW; fixed: the head view box read with
`get`, the destination claimed then canonicalised, `INIT_CWD` taken only when absolute; kept:
seed SQL built by string formatting as the TypeScript, from pipeline values only, and the
suite's clippy allow line), `.claude/audits/2026-10-22-rust-r5-draft-security.md`. Fresh
verifier, three passes (`.claude/audits/2026-10-22-rust-r5-draft-verify.md`): pass 1 found
four unreachable divergences, two aligned (`String(id)` for finding targets, the exact
JavaScript `trimEnd` set), two kept as both sides refuse (an added item with a `null` child,
refused at a later stage; a position beyond 2^64, a different number printed); pass 2 found
one reachable divergence, `null` accepted on the optional `scope`, `position` and `field`
where Zod refused it, now refused alike (three synthetic cases added), and aligned the
re-homing candidates on a set (a path met twice counts once); outcome-identical details
kept: `annotation_names` reads a non-string name as empty, an unlisted counter key keeps
insertion order, the `parseViewBox` error quotes its text. Pass 3 found a repeated key
refused by serde's derive (now read as `JSON.parse` does), an authored NUL-prefixed key
silently dropped by the mark cleanup (now refused at parse), a symbolic link typed with a
trailing `/` followed by `--out` (the path is rebuilt from its components before the check),
and three refusals by design now declared above (lone surrogate, depth, `__proto__`). Pass 4
met C1 to C12 and found the documentation incomplete: the curation files are now read lossily
as the TypeScript read them (a Latin-1 byte had been refused), two contrived splits are
declared above (`1e400` in a discarded value, an inherited member in a field path), and the
NUL-key row and the counts are corrected.
### 11.13 Checkpoint R5.3
Residual risks: the `--check` allowance for the six R5.4 files hides nothing about the
produced files but means the draft folder is not yet compared whole (R5.4 removes it); the
touch marks are a reserved key (a NUL character starts it), refused in any authored value at
parse and removed after each change, so no mark reaches a record or the document; the migration-map replay quirk above
is reproduced, not fixed; the emoji, Markdown and Unicode-table risks of §11.11 stand.
Conditions for R5.4: the owner's validation of this checkpoint; the review drawings
compared as parsed trees against the xmldom files (declaration, prefixes and whitespace
declared), on the R3 layer and compose; `CHANGELOG.md` and `REVIEW-REPORT.md` byte for byte
through `markdown.rs` (the pre-Prettier digests of the ledger as the intermediate check);
the pending list of `--check` removed so the draft folder is compared whole.