From 57b58b3af1ebe6533fae1c6ad90c6f65ec3c4b56 Mon Sep 17 00:00:00 2001 From: Bastien Chanot Date: Thu, 21 May 2026 03:23:30 +0200 Subject: [PATCH] docs(species): refresh PATHOLOGIES-FORMAT for v2.0 contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - schema_version "2.0" everywhere; new Changelog section with v1.0 → v2.0 entries highlighting the breaking change. - New Scope (legal périmètre) section listing inclusions / exclusions and the two flag mechanisms (root scope_disclaimer + leaf boolean). - Clarified SVG ↔ JSON link via strict label equality (not data-anno-id) and cranio-caudal zone ordering rule. - Documented the 3 standardized categories per zone (*-dysfunctions / *-observations / anamnesis) and the 5 dysfunctions taxonomy patterns (head SSB / head peripheral / articular / vertebral hinge / vertebral region). - Documented structural authoring rules (depth ≤ 4, ≥ 2 children per intermediate, sibling-scoped ID uniqueness). - Spelled out the v2.0 requires_vet_referral / description_fr policy (boolean = source of truth; description_fr survives only on differential leaves) and the breaking-change notice for any consumer relying on description_fr.includes('vétérinaire'). - Rewrote the minimal example using v2.0 contract (boolean only, description_fr only when it adds a differential). - Noted Zod's silent strip of unknown fields (e.g. species.notes, per-leaf metadata). - Added current horse.json stats table (26 zones / 792 nodes / 612 leaves / 41 vet leaves). --- docs/PATHOLOGIES-FORMAT.md | 294 +++++++++++++++++++++++++++++++------ 1 file changed, 246 insertions(+), 48 deletions(-) diff --git a/docs/PATHOLOGIES-FORMAT.md b/docs/PATHOLOGIES-FORMAT.md index 4874589a..8c0620d6 100644 --- a/docs/PATHOLOGIES-FORMAT.md +++ b/docs/PATHOLOGIES-FORMAT.md @@ -13,18 +13,44 @@ The catalog is loaded once at module import via boot (Zod stack trace pointing at the offending node) — there is no silent fallback. +**Current schema version: `"2.0"`** — see [Changelog](#changelog) for the +breaking changes from v1.x. + +--- + +## Scope (legal périmètre — important) + +Catalog entries describe **strictly what an animal osteopath may write +in a bilan** under French law: + +- ✅ Palpated osteopathic dysfunctions (SSB lesions, sutures, intra-osseous) +- ✅ Mobility restrictions and muscular tensions observed +- ✅ Visible mechanical asymmetries +- ✅ Clinical observations and consultation motives reported by the owner +- ✅ Anamnesis (reported factors) + +- ❌ Medical diagnoses (Cushing, OCM, arthrosis, ankylosis…) +- ❌ Organic pathologies requiring imaging / blood work / biopsy +- ❌ Anything requiring medical, surgical or pharmaceutical intervention + +The osteopath may **suspect** and **redirect to a veterinarian** but +never poses a medical diagnosis. Two mechanisms enforce this in data: +the root `scope_disclaimer` field (UI surface) and the boolean +`requires_vet_referral` on sensitive leaves (logic surface — see below). + --- ## Top-level shape ```json { - "schema_version": "1.1", + "schema_version": "2.0", "scope_disclaimer": "string non vide — affiché 1× par session dans l'éditeur", "species": { "id": "equine", "name_fr": "Cheval", - "name_en": "Horse" + "name_en": "Horse", + "notes": "optional — clinical context specific to the species" }, "zones": { "": { ... ZoneFindings ... } @@ -34,18 +60,28 @@ silent fallback. | Field | Type | Required | Notes | | ------------------ | ------ | -------- | ----------------------------------------------------------- | -| `schema_version` | string | yes | non-empty, bump on breaking changes | -| `scope_disclaimer` | string | yes | non-empty, shown once per session | +| `schema_version` | string | yes | non-empty, bump on breaking changes; current `"2.0"` | +| `scope_disclaimer` | string | yes | non-empty, shown once per session via `osteo:disclaimer-shown` flag | | `species.id` | string | yes | should match the `SpeciesManifest.id` in the manifest | | `species.name_fr` | string | yes | | | `species.name_en` | string | yes | | +| `species.notes` | string | no | free-text species context; currently stripped by Zod (extend schema before relying on it) | | `zones` | object | yes | dictionary keyed by free-form `zoneKey` → `ZoneFindings` | -`zoneKey` is opaque — kebab-case is the convention. It does NOT have -to match SVG `data-anno-id` values (those are usually generator -strings). The runtime matches SVG zones to JSON zones via -`bone.fr` / `bone.en` ⇄ `zone.name_fr` / `zone.name_en` using the -fuzzy matcher in `src/lib/zoneMatch.ts`. +`zoneKey` is opaque — kebab-case is the convention. It does NOT have to +match SVG `data-anno-id` values (those are usually generator strings). + +**SVG ↔ JSON link is via labels, not IDs.** The runtime matches a +clicked SVG element to a JSON zone by comparing `data-anno-name-fr` / +`data-anno-name-en` against `zone.name_fr` / `zone.name_en`. The v2.0 +authoring rule prescribes **strict equality** (case + accents + spaces); +`src/lib/zoneMatch.ts` keeps a normalize+Levenshtein fallback as a +safety net but content should not depend on it. + +**Zone ordering.** Zones appear in the `zones` dictionary in +**cranio-caudal order** (head → tail). JS object insertion order is +preserved by modern engines for non-numeric keys, and the picker relies +on this — never sort `zones` alphabetically. --- @@ -63,9 +99,39 @@ fuzzy matcher in `src/lib/zoneMatch.ts`. | Field | Type | Required | Notes | | ------------ | --------------- | -------- | --------------------------------------------------------- | | `id` | string | yes | by convention the same string as the parent `zoneKey` | -| `name_fr` | string | yes | matched against SVG `data-anno-name-fr` | -| `name_en` | string | yes | matched against SVG `data-anno-name-en` | -| `categories` | `FindingNode[]` | yes | may be empty | +| `name_fr` | string | yes | **must equal** SVG `data-anno-name-fr` exactly | +| `name_en` | string | yes | **must equal** SVG `data-anno-name-en` exactly | +| `categories` | `FindingNode[]` | yes | three standardized buckets (see below) | + +### Three standardized categories per zone + +Each zone exposes exactly three top-level categories in this order: + +1. **Dysfonctions ostéopathiques** — palpation / manipulation, the core + work. `id` is zone-prefixed (e.g. `atm-dysfunctions`). +2. **Observations / motifs de consultation** — what the owner reports or + what is observed (varies per species). `id` is zone-prefixed (e.g. + `atm-observations`). +3. **Anamnèse / facteurs rapportés** — context. `id` is always plain + `anamnesis` (not zone-prefixed). + +### Five taxonomy patterns for `*-dysfunctions` + +The dysfunctions sub-tree follows one of five patterns derived from the +zone type — degrees of freedom enumerated, muscles by insertion, sutures +by adjacency: + +| Pattern | Zones (horse) | Sub-categories | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| Cranial (SSB axis) | `sphenoid`, `ssb` | `physiological` · `traumatic` · `intraosseous` · `sutures` | +| Cranial (peripheral) | `parietal`, `frontal`, `temporal`, `occipital` | `mobility` · `intraosseous` · `sutures` | +| Articular | `atm`, `shoulder`, `elbow`, `fore-fetlock`, `hind-fetlock`, `hock`, `hip`, `stifle`, `sacroiliac`, `fore-sesamoids` | `articular` · `muscular` · `mechanical` | +| Vertebral hinge | `c0-c1`, `c7-t1`, `t18-l1`, `l6-s1` | `segmental` · `muscular` · `mechanical` | +| Vertebral region | `cervical`, `thoracic`, `lumbar`, `sacral`, `caudal` | `segmental` · [`costovertebral`] · `group` · `muscular` · `mechanical` | + +Special cases: `hyoid` (mobility of the hyoid apparatus / associated +muscles / intra-osseous), `thoracic` (extra `costovertebral` +sub-category). --- @@ -76,9 +142,9 @@ fuzzy matcher in `src/lib/zoneMatch.ts`. "id": "tensions", "name_fr": "Tensions des muscles masticateurs", "name_en": "Masticatory muscle tensions", - "description_fr": "optionnel", - "description_en": "optionnel", - "requires_vet_referral": false, + "description_fr": "optionnel — différentiel clinique spécifique uniquement", + "description_en": "optional — currently authored FR-only", + "requires_vet_referral": true, "sources": [ { ... SourceRef ... } ], "children": [ { ... FindingNode ... } ] } @@ -86,22 +152,75 @@ fuzzy matcher in `src/lib/zoneMatch.ts`. | Field | Type | Required | Notes | | ----------------------- | --------------- | -------- | -------------------------------------------------- | -| `id` | string | yes | unique within its parent's `children` / `categories` | +| `id` | string | yes | unique within its **siblings only** (NOT globally) | | `name_fr` | string | yes | | | `name_en` | string | yes | | -| `description_fr` | string | no | surfaced above the children list in the picker | -| `description_en` | string | no | reserved for future locale switch | -| `requires_vet_referral` | boolean | no | adds a ⚠ badge in picker and a ⚠ prefix in PDF | +| `description_fr` | string | no | see policy below (v2.0) | +| `description_en` | string | no | reserved — current catalog FR-only | +| `requires_vet_referral` | boolean | no | **source of truth** for the vet flag (v2.0) | | `sources` | `SourceRef[]` | no | citations, see below | | `children` | `FindingNode[]` | no | absent or `[]` → leaf (selectable checkbox) | -**Leaf vs intermediate:** +### Leaf vs intermediate + +```ts +const isLeaf = (n) => !n.children || n.children.length === 0 +``` - `children` missing or empty → **leaf**. Rendered as a checkbox. Selecting it emits a `Finding` with the full path snapshot. - `children` non-empty → **intermediate**. Rendered as a drill-down button. The badge next to it counts selected descendants. +### Structural constraints (authoring rules) + +- Maximum depth: **4 levels** (category → sub-category → [sub-sub-category] → leaf). +- Every intermediate node has **at least 2 children**. +- `requires_vet_referral` is **only** set on leaves, never on categories. +- IDs are unique among **siblings only**, not globally — `articular`, + `muscular`, `mechanical`, `anamnesis`, `trauma-direct` legitimately + repeat across zones. Any `findNodeById` helper must therefore be + scoped to a single zone root. + +### `requires_vet_referral` and `description_fr` (v2.0) + +Since v2.0 the boolean `requires_vet_referral: true` is the **only** +source of truth for the vet-orientation flag. The generic +"orienter vers vétérinaire" wording has been **purged** from +`description_fr` on leaves where the boolean alone suffices. + +`description_fr` survives on a vet-flagged leaf **only** when it adds a +clinical differential the boolean cannot carry — a specific cause to +rule out (neurological, sinus, ligament, rotular, cutaneous, osseous, +traumatic…). Example: + +```json +{ + "id": "deglutition-difficulty", + "name_fr": "Difficulté de déglutition", + "name_en": "Swallowing difficulty", + "description_fr": "Une difficulté de déglutition impose d'écarter une cause médicale/neurologique : orienter vers vétérinaire avant intervention ostéo.", + "requires_vet_referral": true +} +``` + +**Consumer rule:** + +```ts +const requiresVetReferral = (n) => n.requires_vet_referral === true +``` + +**Breaking change from v1.x.** Any consumer that detected the flag by +scanning `description_fr.includes('vétérinaire')` will silently miss +vet leaves on a v2.0 catalog (25 leaves had that text removed in the +v2.0 purge). All in-tree consumers (`FindingsTreePicker`, +PDF `observationPage`) already key off the boolean. + +Picker surface: a ⚠ badge is shown next to vet-flagged leaves. PDF +surface: the snapshot label is prefixed `⚠` in the +`CONSTATS — ` section. If a `description_fr` is also present, +it is rendered as an additional context line below the children list. + --- ## SourceRef (optional citation) @@ -120,13 +239,16 @@ fuzzy matcher in `src/lib/zoneMatch.ts`. | `citation` | string | yes | non-empty, human-readable | | `url` | string | no | must pass `z.string().url()` if present | +Sources are optional in v2.0; recommended on leaves carrying clinical +weight (vet-referral leaves, differential descriptions). + --- ## Minimal complete example ```json { - "schema_version": "1.1", + "schema_version": "2.0", "scope_disclaimer": "Les éléments listés correspondent au périmètre légal de l'ostéopathie animale : dysfonctions ostéopathiques palpées, observations cliniques et motifs de consultation. Aucun diagnostic médical n'est posé. Toute pathologie organique relève du vétérinaire.", "species": { "id": "canine", @@ -140,30 +262,42 @@ fuzzy matcher in `src/lib/zoneMatch.ts`. "name_en": "Hip joint", "categories": [ { - "id": "dysf", - "name_fr": "Dysfonctions ostéopathiques", - "name_en": "Osteopathic dysfunctions", + "id": "hanche-dysfunctions", + "name_fr": "Dysfonctions ostéopathiques de la hanche", + "name_en": "Hip osteopathic dysfunctions", "children": [ { - "id": "compression", - "name_fr": "Compression articulaire", - "name_en": "Joint compression", - "description_fr": "Restriction de mobilité dans plusieurs plans" - }, - { - "id": "instabilite", - "name_fr": "Instabilité", - "name_en": "Instability", - "requires_vet_referral": true, - "sources": [ + "id": "articular", + "name_fr": "Restrictions de mobilité articulaire", + "name_en": "Joint mobility restrictions", + "children": [ { - "type": "journal", - "citation": "Smith et al., 2024", - "url": "https://example.com/paper" + "id": "compression", + "name_fr": "Compression articulaire", + "name_en": "Joint compression" + }, + { + "id": "laxite", + "name_fr": "Laxité perçue", + "name_en": "Perceived laxity", + "description_fr": "Une laxité perçue peut évoquer une atteinte ligamentaire : orienter vers vétérinaire avant intervention ostéo.", + "requires_vet_referral": true } ] } ] + }, + { + "id": "hanche-observations", + "name_fr": "Observations / motifs de consultation", + "name_en": "Observations / consultation motives", + "children": [ /* ... */ ] + }, + { + "id": "anamnesis", + "name_fr": "Anamnèse / facteurs rapportés", + "name_en": "Anamnesis / reported factors", + "children": [ /* ... */ ] } ] } @@ -177,7 +311,12 @@ fuzzy matcher in `src/lib/zoneMatch.ts`. - Every required `string` field must be non-empty (`z.string().min(1)`). - `url` fields must parse via `z.string().url()`. -- Recursion through `children` is `z.lazy` — depth is unbounded. +- Recursion through `children` is `z.lazy` — depth is unbounded at the + schema level (authoring rule caps it at 4). +- Unknown fields on objects are **silently stripped** by Zod's default + `z.object` behaviour. Extra metadata (e.g. `species.notes`, + custom per-leaf `metadata`) survives in the JSON file but is not + surfaced at runtime until the schema declares it. - A bad JSON throws a Zod error at `pathologies.ts` import time, with a path pointing at the offending node — the editor never starts with a half-valid catalog. @@ -200,13 +339,26 @@ When the practitioner toggles a leaf checkbox, the picker emits a ``` The snapshot fields freeze the label so already-exported reports stay -legible even if the catalog is later edited or renamed. The `path` is -kept for future re-link / migration tooling but is never required to -re-render an existing report. +legible even if the catalog is later edited or renamed (BDR-010). The +`path` is kept for future re-link / migration tooling but is never +required to re-render an existing report. In the PDF, findings are grouped by `zoneId` (one `CONSTATS — ` section per zone) followed by a single -`CONSTATS LIBRES` section listing the free-text additions. +`CONSTATS LIBRES` section listing the free-text additions. Vet-referral +leaves are prefixed with ⚠ in the rendered list. + +--- + +## Current `horse.json` stats + +| Metric | Count | +| --------------------------------------- | ----------- | +| Zones (9 head + 17 body) | 26 | +| Total nodes | 792 | +| Leaves | 612 | +| Leaves with `requires_vet_referral` | 41 | +| File size (indented) | ~177 KB | --- @@ -215,10 +367,12 @@ In the PDF, findings are grouped by `zoneId` (one 1. Copy `src/domain/species/equine/pathologies.json` as a reference, or scaffold a new species via `pnpm scaffold:species` (writes a minimal valid skeleton). -2. Edit the JSON, respecting the schema above. -3. Run `pnpm dev` — Vite HMR reloads the module, Zod parses the new +2. Edit the JSON, respecting the schema and structural rules above. +3. Ensure every `zone.name_fr` / `zone.name_en` matches the SVG + `data-anno-name-fr` / `data-anno-name-en` exactly (case included). +4. Run `pnpm dev` — Vite HMR reloads the module, Zod parses the new tree, errors surface immediately on save. -4. The picker and PDF pick up changes without any code edit. +5. The picker and PDF pick up changes without any code edit. For production deploys, ship the new JSON via the normal build pipeline (`pnpm build`) — there is no runtime hot-reload outside the dev server. @@ -231,5 +385,49 @@ For production deploys, ship the new JSON via the normal build pipeline | ------------------------------------------ | -------------------------------------------------------------------------- | | `src/domain/schema/findings.ts` | Zod definitions: `FindingNode`, `ZoneFindings`, `SpeciesFindings`, `SourceRef` | | `src/domain/schema/observation.ts` | `Finding` snapshot stored on an observation | -| `src/domain/species/equine/pathologies.json` | Authoritative reference catalog | -| `src/lib/zoneMatch.ts` | SVG zone label ↔ JSON zone name matcher | +| `src/domain/species/equine/pathologies.json` | Authoritative reference catalog (v2.0, 26 zones) | +| `src/lib/zoneMatch.ts` | SVG zone label ↔ JSON zone name fallback matcher | + +--- + +## Changelog + +### v2.0 (current) — breaking + +- `requires_vet_referral` boolean becomes the **sole source of truth** + for the vet-orientation flag. +- Generic vet wording purged from `description_fr` on 25 leaves where + the boolean already conveyed the same info. `description_fr` survives + on the 16 leaves carrying a clinical differential (cause to rule out). +- Consumer helper simplified to `node.requires_vet_referral === true`. + Any prior `description_fr.includes('vétérinaire')` fallback **must + migrate** to the boolean. +- Horse coverage extended placeholder 3 zones → full 26 zones (9 head + + 17 body), 792 nodes, 612 leaves. + +### v1.2 + +- Added the optional boolean `requires_vet_referral` on leaves + (still co-existed with vet wording in `description_fr` for + backward compatibility — removed in v2.0). +- Documented SVG ↔ JSON link via `name_fr` / `name_en` strict match + (not `zones.` ↔ `data-anno-id`). +- Documented the 5 dysfunctions taxonomy patterns. +- Explicit cranio-caudal zone ordering. +- Explicit structural constraints (depth ≤ 4, ≥ 2 children per + intermediate, sibling-scoped ID uniqueness). + +### v1.1 + +- Removed medical diagnoses (OCM, Cushing, hyperthyroidism, arthrosis, + ankylosis…) — out of legal scope. +- Reformulated diagnoses as observations ("Suite de X", "X rapporté(e)"). +- Added `scope_disclaimer` at the root + initial `description_fr` + vet-orientation hints on sensitive motives. +- Standardized 3 categories per zone (Dysfunctions / Observations / + Anamnesis). + +### v1.0 + +- Initial schema mixing osteopathic dysfunctions with medical + diagnoses — non-compliant with French legal scope, corrected in v1.1.