100 lines
7.1 KiB
Markdown
100 lines
7.1 KiB
Markdown
# CONTRACT: Rust R5.3, the draft side of the anatomical pipeline (changeset applier, migration map, stats, seed SQL)
|
|
|
|
- date: 2026-10-22 | branch `feature/rust-r5-pipeline-core` | plan `.claude/tasks/plans/2026-10-22-rust-r5-pipeline-core.md` §B.5 row R5.3
|
|
- brief: owner 2026-10-22 « Validation R5.1b / R5.2 et autorisation R5.3 » (applied as written; its §1 to §9 are the clauses below)
|
|
- predecessor: R5.2 contract `.claude/tasks/contracts/2026-10-22-rust-r5-f1-importer.md` (the legacy importer, `import-equine --check | --out`)
|
|
|
|
## Scope
|
|
|
|
Port `packages/anatomy/src/curation/{schema,targets,fields,ops,rename,apply,types,migration-map,stats,seed,pipeline}.ts`
|
|
(the draft side without the review drawings and the two Markdown reports, which are R5.4) into
|
|
`crates/core/src/curation/draft/**` behind the existing `curation` feature, and extend the
|
|
`import-equine` binary to the `draft/` folder. Out of scope: `overlay.ts`, `app-review.ts`,
|
|
`changelog.ts`, `review-report.ts`, `assets.ts` (`stripLegacyAnnotations`: the cleaned `horse.svg`
|
|
is frozen, read as bytes), the fingerprint convention (R5.6), the upload tool (R5.5), any deletion
|
|
under `packages/`.
|
|
|
|
## Clauses (each one checkable)
|
|
|
|
C1. **Inputs.** The core reads the legacy `ImportResult` (R5.2), the bytes of the frozen
|
|
`draft/assets/horse.svg`, the head view box text, `curation/references.json` and
|
|
`curation/changes.json` as texts. No `std::fs`, no clock in `crates/core/src/curation/**`
|
|
(the binary `crates/core/src/bin/import_equine.rs` is the only file allowed the file system).
|
|
|
|
C2. **Strict schemas.** `changes.json` and `references.json` are refused on: an unknown key in any
|
|
object, a wrong type, an `id` not matching `^CHG-\d{3,}$`, an empty `title.fr` / `title.en` /
|
|
`rationale` / target / field / rename id / cited reference id / `question`, an empty `ops`, an
|
|
empty `cite.reference_ids`, a level C change without a `question`, a duplicate change id, a
|
|
duplicate reference id, a position that is not a non-negative integer or a strict
|
|
`{after}` / `{before}` object, a reference failing the R2 `Reference` contract. `priority`
|
|
defaults to `medium`. Declared difference: a `set` without `value` is refused (TypeScript
|
|
wrote `undefined`, i.e. dropped the key).
|
|
|
|
C3. **Applier semantics** (`apply.rs`, `ops.rs`, `rename.rs`, `targets.rs`, `fields.rs`): the
|
|
six ops behave as `ops.ts` on the plain JSON document (insertion order of keys, `review_status`
|
|
appended last when created), with the settable table of `fields.ts`, the target grammar of
|
|
`targets.ts`, the rename cascade of `rename.ts` (one record per rewrite), `assertDeclared`,
|
|
`assertNotReviewed`, and the review rule of `apply.ts` (every touched finding or annotation of a
|
|
B or C change set `to_confirm` with a record, first-touch order, items removed from the document
|
|
skipped). Any op that cannot apply exactly refuses with the change id and op index; the result
|
|
then passes the R2 shape (`AnatomicalSheetDocument`) and integrity (`validate_sheet_document`)
|
|
gate, errors refuse, warnings are returned.
|
|
|
|
C4. **Records.** Every record is `{change, op, target, field, before, after}` with `change` in
|
|
the Zod shape order (`id, level, kind, title, rationale, reference_ids, question?, priority`),
|
|
`op` in the Zod shape order of its kind, absent values as `null`.
|
|
|
|
C5. **Migration map** (`migration_map.rs`): `buildReportMigrationMap` as `migration-map.ts`
|
|
(replay of rename / remove / move records, zone renames, annotation and view renames, the
|
|
finalPaths check, unique re-homing, stats `nodes / identical / remapped / rehomed / removed`).
|
|
|
|
C6. **Stats** (`stats.rs`): `documentStats` with its 17 fields in the TypeScript key order,
|
|
the fixed-key counters (`point, zone, detail_trigger`; `inherited, reviewed, to_confirm`)
|
|
extended by unlisted values as JavaScript does.
|
|
|
|
C7. **Seed SQL** (`seed.rs`): `renderDraftSeedSql` byte for byte (header, sheet insert, asset
|
|
inserts, `insert_sheet_draft`, converging update, the dollar tag refusal, `trimEnd`).
|
|
|
|
C8. **Draft artifacts** (`pipeline.rs`): `build_equine_draft` runs CHG-000 (asset record of the
|
|
frozen bytes: sha256, byte size, uuid; `view:main.svg_asset_id`, `view:head.svg_asset_id = null`,
|
|
`view:head.view_box` from the head SVG's viewBox) then the authored changes, refuses a changeset
|
|
reusing `CHG-000`; `render_draft_artifacts` returns `document.json`, `assets.json`,
|
|
`sheet-ref.json` (`document_sha256` = sha256 of the `document.json` bytes, the historical rule),
|
|
`report-migration-map.json`, `equine_draft.sql`, in the TypeScript order, plus the byte copy
|
|
`assets/horse.svg`.
|
|
|
|
C9. **Parity proofs** (`crates/core/tests/curation_draft.rs`): the six R5.3 files of the
|
|
committed `draft/` byte for byte; the `pipeline.json` draft section (sheetId, 46 changes, 1
|
|
asset, statsBefore, statsAfter, issues, migrationStats, 825 records) equal under the JS compact
|
|
print; two runs byte-equal; the 612 legacy leaves migrated 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.
|
|
|
|
C10. **Synthetic differential** (`oracles/r5/curation-synthetic.json`, generator
|
|
`packages/anatomy/tests/r5.curation-synthetic-oracles.test.ts`, `MAKE_R5_ORACLES=1`): changesets
|
|
on the mini sheet covering every op kind, numeric and anchored positions, subtree scopes, the
|
|
review rule on levels A / B / C, the five rename cascades, a reference rename, re-homing, and the
|
|
refusal classes of `curation.apply.test.ts` and `curation.schema.test.ts`; each accepted case
|
|
freezes the formatted document, the records, the stats, the migration map and the seed SQL, each
|
|
refused case the refusal; the Rust suite reproduces every accepted case byte for byte and refuses
|
|
every refused case.
|
|
|
|
C11. **Binary and script.** `import-equine --check` compares `legacy-import/` and `draft/` with
|
|
the committed folders and writes nothing; the R5.4 files (`review/*.svg`, `CHANGELOG.md`,
|
|
`REVIEW-REPORT.md`) are listed as pending and not counted (marked `shortcut:` for R5.4).
|
|
`import-equine --out <dest>` writes `<dest>/legacy-import/**` and `<dest>/draft/**`, refuses an
|
|
empty path, a path that exists and is not a directory, a symlink, a folder holding any file;
|
|
never deletes. `scripts/import-equine.sh` + root script `r5:import-equine` forward the
|
|
arguments; `pnpm import:equine` (TypeScript) unchanged.
|
|
|
|
C12. **Frozen references untouched.** No file under `supabase/seed/**`, `crates/core/tests/oracles/**`
|
|
(except the new `curation-synthetic.json`), `apps/app/tests/fixtures/**`,
|
|
`packages/core-wasm/tests/n-1/**` changes; `documentSha256` stays `27c7383c…2660`; no gated
|
|
reader (`domain/{archive/read,report/rebase,report/read,session}.rs`, `pdf/{read,json_js,import}.rs`)
|
|
changes; `packages/anatomy` and `packages/domain` keep every test (anatomy gains the generator).
|
|
|
|
C13. **Gates.** `pnpm rust:check` green, `pnpm check:all` green, security auditor PASS on the
|
|
diff, this contract verified CONFORME by a fresh verifier; RUST.md §11.12 (R5.3) and §11.13
|
|
(checkpoint) written, CHANGELOG Unreleased, CLAUDE.md command list; differences declared one by
|
|
one. No merge, no R5.4, no fingerprint switch, no release, no deploy.
|