58 lines
8.1 KiB
Markdown
58 lines
8.1 KiB
Markdown
# CONTRACT — R2 closure: L1 lone UTF-16 surrogates refused, never replaced
|
|
- date: 2026-10-14 | flow: ad-hoc fix on the R2 branch, verifier gate | branch: feature/rust-r2-domain-core
|
|
- status: dispatched after the code, test and doc commits
|
|
- spec: owner brief 2026-10-14 §2 (L1) + §3 (deletions) + answers: approach = refusal + quarantine (not preservation), import message = detailed wording; BDR-051 in `.claude/memory/decisions.md`; `docs/development/RUST.md` §8.7 item 1
|
|
- diff range: 36316cf..HEAD (run every CHECK from the repository root; `. scripts/rust-env.sh` first for cargo)
|
|
|
|
## REQUEST (IMMUTABLE)
|
|
Do not accept the silent transformation of an isolated UTF-16 surrogate into U+FFFD when historical data is read. Preserve user data integrity strictly: faithful preservation where possible, otherwise controlled refusal or quarantine of the data concerned, with the original content kept and an explicit message. Never delete or silently transform unreadable historical data. Add the non-regression tests needed, covering JSON strings with a lone surrogate and normal data. (Owner chose refusal + quarantine; preservation would need an architecture change.) Also approved: deletion of the old `zoneInteraction` suite and of the helper that skipped tests without the wasm module, provided the behaviours stay covered and the checks fail when an essential Rust feature becomes unavailable; no oracle needed by R3/R4 removed. No GUI change, no deploy.
|
|
|
|
## ACCEPTANCE CRITERIA
|
|
1. No replacement of lone surrogates remains anywhere in the code.
|
|
CHECK: grep -rn "replace_lone_surrogates" crates packages apps --include=*.rs --include=*.ts | wc -l; grep -c 'push_str("\\\\uFFFD")' crates/core/src/domain/js.rs
|
|
EXPECT: 0 / 0
|
|
2. The native Rust gate is green.
|
|
CHECK: bash scripts/rust-check.sh > /tmp/l1-verify-rust.log 2>&1; echo "exit $?"
|
|
EXPECT: exit 0
|
|
3. The core carries at least 142 passing tests, none failing.
|
|
CHECK: . scripts/rust-env.sh && cargo test -p faunosteo-core 2>&1 | grep "test result" | awk '{s+=$4; f+=$6} END {print s, f}'
|
|
EXPECT: first number ≥ 142, second 0
|
|
4. Every core entry that reads JSON text names the refusal `lone_surrogate` (operation inputs and sheet.check through the `From<JsonReadError>` impl, draft restore and archive import through their own variants).
|
|
CHECK: grep -c '"lone_surrogate"' crates/core/src/ops.rs crates/core/src/facade.rs; grep -c "LoneSurrogate" crates/core/src/domain/session.rs
|
|
EXPECT: ops.rs:2 facade.rs:2 / 4
|
|
5. The application treats the kind as unreadable draft content (quarantine), maps it on import to its own error and message in both dictionaries, and the publish gate reads it as content.
|
|
CHECK: grep -c "'lone_surrogate'" apps/app/src/state/reportStore.ts apps/app/src/pdf/import.ts apps/app/src/app/routes/HomeRoute.tsx packages/supabase/src/anatomical-sheets.ts; printf "%s/%s\n" $(grep -c "'home.import.error_lone_surrogate'" apps/app/src/i18n/fr.ts) $(grep -c "'home.import.error_lone_surrogate'" apps/app/src/i18n/en.ts)
|
|
EXPECT: reportStore.ts:1 import.ts:3 HomeRoute.tsx:1 anatomical-sheets.ts:1 / 1/1
|
|
6. The Node suites pass on the rebuilt module, with the new cases (app 320, supabase 40, core-wasm 26, domain 262).
|
|
CHECK: bash scripts/wasm-build.sh > /dev/null 2>&1; for p in app supabase core-wasm domain; do ./node_modules/.bin/pnpm --filter @faunosteo/$p exec vitest run 2>&1 | grep -E "^ +Tests "; done
|
|
EXPECT: Tests 320 passed (320) / Tests 40 passed (40) / Tests 26 passed (26) / Tests 262 passed (262)
|
|
7. No oracle, frozen fixture, N-1 copy, golden or seed file changed in the range.
|
|
CHECK: git diff --stat 36316cf..HEAD -- crates/core/tests/oracles apps/app/tests/fixtures packages/domain/tests/fixtures packages/core-wasm/tests/n-1 supabase/seed packages/pdf/tests packages/anatomy/tests | wc -l
|
|
EXPECT: 0
|
|
8. The tests cover a lone surrogate (high, low, in a key, in a v2 and a v3 report, in a draft, an archive, an attachment, an operation input, a sheet document) and normal data (pairs, literal backslash-u text, a genuine U+FFFD) and assert the original text is kept.
|
|
CHECK: grep -cE "fn (a_draft_with_a_lone|an_archive_with_a_lone|an_attachment_with_a_lone|normal_text_with_pairs)" crates/core/tests/archive_rules.rs; grep -cE "fn (lone_surrogate_escapes_are_found|a_lone_surrogate_refuses|normal_text_reads_unchanged)" crates/core/src/domain/js.rs; grep -c "lone surrogate" apps/app/tests/unit/state.quarantine.test.ts apps/app/tests/unit/pdf.import.test.ts packages/supabase/tests/anatomical-sheets.test.ts packages/core-wasm/tests/facade.test.ts
|
|
EXPECT: 4 / 3 / each file ≥ 1
|
|
9. A missing or stale wasm module fails the suites instead of skipping them, and no core suite is conditionally skipped.
|
|
CHECK: grep -c "stale' : 'missing'" packages/core-wasm/tests/global-setup.ts; grep -l "core-wasm/tests/global-setup.ts" apps/app/vitest.config.ts packages/supabase/vitest.config.ts packages/core-wasm/vitest.config.ts | wc -l; grep -rn "skipIf\|runIf\|isCoreBuilt" apps/app/tests packages/core-wasm/tests packages/core-wasm/src packages/supabase/tests --include=*.ts | grep -v "e2e/" | wc -l
|
|
EXPECT: 1 / 2 (core-wasm references it as `tests/global-setup.ts`) / 0
|
|
10. The deleted TypeScript editor cases keep a same-named Rust test each.
|
|
CHECK: for n in opens_the_detail_view_for_the_trigger_even_without_an_active_observation only_activates_a_fallback_observation_when_none_is_active always_opens_the_vertebra_picker_on_a_spine_zone routes_bilateral_zones_through_the_side_picker_or_clears_both_sides toggle_zone_adds_a_zone_with_snapshots_then_removes_it ensure_zone_keeps_an_existing_zone_and_reports_its_index add_sides_appends_only_the_missing_sides_and_never_removes_one remove_zone_at_removes_one_zone_by_index_and_keeps_findings detail_view_zones_are_distinct_from_main_view_zones_with_the_same_id collects_vertebrae_across_spine_zones_the_priority_zone_first replaces_per_region_prunes_emptied_zones_and_spawns_zones_for_new_regions keeps_non_spine_zones_untouched_and_ignores_unknown_regions; do grep -c "fn $n" crates/core/tests/editor_rules.rs; done | sort | uniq -c
|
|
EXPECT: 12 1
|
|
11. No interface component, style or signed-in screen changed; HomeRoute gains only the two lines of the new case.
|
|
CHECK: git diff --stat 36316cf..HEAD -- apps/app/src/components apps/app/src/styles apps/app/src/app/routes/app apps/app/src/app/routes/auth | wc -l; git diff 36316cf..HEAD -- apps/app/src/app/routes/HomeRoute.tsx | grep -c "^[+-][^+-]"
|
|
EXPECT: 0 / 2
|
|
12. Documentation states the owner's decision and the refusal paths.
|
|
CHECK: grep -c "owner decision 2026-10-14, BDR-051" docs/development/RUST.md; grep -c "Lone UTF-16 surrogates refused, never altered" CHANGELOG.md; grep -c "lone_surrogate" docs/PDF-FORMAT.md
|
|
EXPECT: 1 / 1 / 1
|
|
13. The whole pre-merge gate passes.
|
|
CHECK: bash scripts/check-all.sh > /tmp/l1-verify-all.log 2>&1; echo "exit $?"; grep -c "== all checks passed" /tmp/l1-verify-all.log
|
|
EXPECT: exit 0 / 1
|
|
|
|
## CLARIFICATIONS
|
|
- The editor test list has 13 TypeScript cases; "toggles plain zones; the ten bilateral annotations and the 18 others split as the sheet says" maps to `toggles_plain_zones_and_splits_the_observable_annotations_as_the_sheet_says` (renamed: 28 is not the draft's count), hence 12 exact names in criterion 10.
|
|
- `crates/core/tests/common/mod.rs::oracle_file` writes each lone escape of an oracle file out as literal text for the test loader only: the oracle files are frozen TypeScript evidence, not user data, and their raw text is still what the L1 test reads.
|
|
- The RustSec advisories stage of `check-all.sh` is warn-only by design (RUST.md); its rustls findings predate this range.
|
|
|
|
## FILE SCOPE
|
|
crates/core/**, packages/domain/tests/r2-characterisation.test.ts, apps/app/src/{app/routes/HomeRoute.tsx,core/sheetOps.ts,i18n/fr.ts,i18n/en.ts,pdf/import.ts,state/reportStore.ts}, apps/app/tests/unit/{state.quarantine.test.ts,pdf.import.test.ts,routes.HomeRoute.import.test.tsx}, packages/supabase/src/anatomical-sheets.ts, packages/supabase/tests/anatomical-sheets.test.ts, packages/core-wasm/src/node.ts, packages/core-wasm/tests/facade.test.ts, docs/development/RUST.md, docs/PDF-FORMAT.md, CHANGELOG.md, .claude/tasks/**, .claude/memory/**
|