Files
bchanot a6346105f1 docs(docs): V1-1 contract approved, technical design for review
Owner ratified the V1-1 business decisions. The contract now records them
as approved, adds the nomenclature, the proposed SQL schema, RLS, RPCs,
technical limits, journeys and test plan, and lists the choices left for
the owner. OPEN_QUESTIONS, plan, DOMAIN_MAP, README and CLAUDE.md follow.
2026-10-25 19:15:35 +01:00

18 KiB

Open questions, contradictions and flagged decisions

Status: Step 0 deliverable, 2026-10-08. Two lists: (A) contradictions, ambiguities or technically risky points found when confronting faunosteo-business-architecture.md with the code and the audit, and (B) questions for the developer that change architecture or development order. Items that are merely interesting are left out.

Status (revised 2026-10-25, P0 and V1-1 ratification)

The analysis below is the 2026-10-08 text, kept as written; this table says what has been settled since and by which record (BDR = .claude/memory/decisions.md, D-R = RUST_ARCHITECTURE_REVIEW.md Annex A). Paths it cites under public/species/ and public/pathology-editor.html no longer exist (deleted at Step 5).

Item Status Settled by / where it stands
C1 vertebral formula settled ordered vertebral_config.regions, free codes (BDR-031)
C2 report-only points open localAnnotations reserved empty in Report v3 (BDR-038); promotion semantics undecided (Q6a); defining it later is a report version bump
C3 worker on day one settled Rust worker built at Step 8 / R1 (BDR-044, BDR-048)
C4 global client record settled (owner ratification 2026-10-25, BDR-073) records belong to a workspace (workspaces, workspace_members; one personal workspace per practitioner in V1-1, cabinet workspaces later without destructive transfer); no global directory shared between practitioners, no data visible between them; contract V1-1_OWNERS_ANIMALS.md §4, D2
C5 animal update rights settled (owner ratification 2026-10-25, BDR-073) writes reserved to workspace members with a write right, in V1-1 the practitioner in their personal workspace; no retroactive silent change of a finished bilan; V1-1 contract §6.1, §6.4
C6 unverified accounts settled (owner ratification 2026-10-25, BDR-073) email confirmed, professional status verified and platform role are three distinct notions; a confirmed email gives private use of the workspace; verification (Step 9) required later for public features presenting a verified professional; no verified status by default; statuses are not platform roles (BDR-026); V1-1 contract §6.2. Replaces the 2026-10-08 assumption below (no clients or reports before verification)
C7 « Observation » vocabulary settled finding category kind observation renamed consultation_reason (BDR-033 point 5); Observation stays the report block
C8 drafts per sheet settled one draft per sheet, partial unique index (BDR-032)
C9 detail view asset settled nullable svg_asset_id, crop by view_box; the equine head is a crop of one cleaned drawing (BDR-031, BDR-036, BDR-037)
C10 Edge Functions on a small VPS Edge part settled, hosting open Edge Functions retired, Rust services instead (D-R9, BDR-045); VPS sizing and hosting = Q2
C11 restore after the free window open Step 11 / 14 with the quota decision
C12 SVG sanitisation vs direct upload settled (mechanism) quarantine key, status column, closed policies, sandboxed Rust decoder (BDR-048, STORAGE.md); user SVG upload arrives with Step 13 through the core's SVG reader
C13 CLAUDE.md rules broken settled references registry replaces "≥ 1 source" (BDR-036); contracts are Rust (R2)
C14 locale of stored PDFs open artifact column at Step 15; the archive envelope already records the locale (PDF-FORMAT.md)
Q1 v2 PDFs in use partly settled v2 import is production code (BDR-038, BDR-039); whether real v2 files exist is unanswered
Q2 hosting open blocks any production backend (TODO RR-5); BDR-049 fixes only the DEV / STAGING / PROD split
Q3 non-mammal layouts settled free region codes (BDR-031)
Q4 external use of the pathology editor moot the tool was deleted at Step 5 (BDR-038); content changes go through curation/changes.json until the Step 17 editor (owner confirmed 2026-10-25)
Q5 one or two equine assets settled one cleaned drawing, head as crop (BDR-036, BDR-037)
Q6 manual points, shared client records open (a); (b) settled by C4 (a) as C2; (b) no shared record (C4 ratified), so edit rights live inside a workspace (V1-1 contract §6)
Q7 phone and email providers open Step 7 shipped email only; needed before production SMTP and phone verification
Q8 public site framework settled Astro (D-R8, validated with BDR-045), Rust exception recorded
Q9 catalog anomalies settled, against the 2026-10-08 recommendation no medical correction at import, anomalies reported, degraded slugs normalised (BDR-034); later corrections through curation changes (BDR-036, BDR-037)

Conflicts raised by P0 and their resolution (2026-10-25)

  1. Step 17 keeps the plan's merged-editor scope, but the legacy editors were deleted at Step 5 (BDR-038): until Step 17, no screen edits sheet content. Resolved (owner, 2026-10-25): no graphic editor that changes or publishes anatomical content until Step 17; reference changes go through the curation sources and the Rust pipeline, reviewed, tested and versioned. Annotating a bilan is distinct from changing the anatomical reference and never touches curation/changes.json.
  2. Publication of the official equine sheet: the plan's Step 13 used to expect "v1 published"; BDR-034 and BDR-037 keep it a draft until a platform admin publishes after business review. Confirmed (owner, 2026-10-25): the equine sheet stays a draft until business validation, and nothing publishes it automatically. Still open for V1-2: who triggers the review, and whether V1-2 may serve the unpublished draft to signed-in practitioners.
  3. Recorded decision BDR-041 calls professional verification "Step 11"; the plan numbers it Step 9. Resolved: the plan's numbering is kept and the correction is the new entry BDR-072 (the registry is append-only, BDR-041 is not edited).
  4. README, DEPLOY and CHANGELOG mixed the live 0.1.0 (local tool, no backend) with the unreleased develop (Supabase, worker, Rust core). Resolved in P0: README separates the public 0.1.0, develop, DEV-only features and planned work; CHANGELOG keeps every unreleased change under Unreleased; DEPLOY marks its historical, unverified and unsafe parts, and the CSP example as not production-ready. The fixes themselves stay with TODO RR-5.

A. Contradictions, ambiguities, risky decisions

C1. Vertebral formula shape (architecture §7.2 vs §23.2)

§7.2 shows "vertebral_formula": { "C": 7, "T": 13, "L": 7, "S": 3, "Cd": 20 }, the same fixed five-key object as today's VertebralFormula. §23.2 asks to "remove hard-coded five-region assumptions from generic domain code". The canonical document must use an ordered list of regions { code, label_fr, label_en, count } and the report must store the region code, otherwise the report schema keeps the z.enum(['C','T','L','S','Cd']) of observation.ts:7. This plan assumes the ordered list. See also Q3.

C2. Report-only manual points vs "report references an immutable sheet version" (§3.2 step 7, rule 3)

"A manually created point exists only in this report until promoted to a personal sheet." Such a point is not in any sheet version, so the report document must carry localAnnotations[] (geometry, view id, names, optional finding free text) and the PDF must render them. The architecture does not say where they live or how promotion rewrites the report (does the report then reference a new version of the personal sheet?). Decision needed before the report document v3 is frozen. See Q6.

C3. Worker on day one (§21.1) vs PostgreSQL-backed jobs first (§22.3)

Not a contradiction in substance, but the monorepo tree lists apps/worker as if it existed from the start. The plan creates it at the first job that cannot be a SQL function (reminders / calendar sync).

C4. Global client record shared across practitioners (§2.3, §6)

clients is "a global Faunosteo person record, not a copy per practitioner". Two practitioners with a care relationship to the same person then edit the same first_name/last_name/notes_general. Risks: one practitioner's edit silently changes another's records; notes_general is clinical-adjacent and must not be shared by default. The architecture also requires that identity matching never reveals another relationship. The plan assumes: core identity fields editable only by the creating practitioner or the claimed client account, per-relationship notes in a separate table, and a verification flow for linking. Q6 asks for confirmation. Technically dangerous if left as a plain shared row.

C5. Animal update rights "owner-controlled" (§17.3) with no client accounts in MVP (§20)

In the MVP the owner has no login. The rule "update is owner-controlled, with practitioner update permitted only after a consultation context or explicit owner permission" is unenforceable as written. Plan assumption: the practitioner who created the animal (or an org member with the relationship) can update it; owner control starts with the client portal (post-MVP).

C6. What an unverified account may do (§3.1, §5)

"A non-verified account must not access full professional functionality." Ambiguous: may it create clients/animals and drafts? May it complete a report? Plan assumption: unverified = can set up profile, cabinet invitation acceptance, browse public sheets; cannot create clients/animals/reports. Affects the entitlement capability list. Confirm.

C7. Vocabulary collision on "Observation" (audit 05 §1)

In the code an Observation is a group of zones + findings + severity + comment; in the catalog "Observations / motifs de consultation" is a finding category; the architecture lists "finding/observation/anamnesis tree". The product vocabulary must fix one word for each before UI strings and schema names are created in the SaaS. Plan uses: Observation = the report block (unchanged), Finding = a leaf, Finding category = a tree root.

C8. Multiple drafts per sheet (§7.1)

anatomical_sheet_versions.status ∈ {draft, published, deprecated} and current_version_id on the sheet. Nothing says whether a sheet may hold more than one draft at a time or who may edit a draft (creator only? org members?). Plan assumption: at most one draft per sheet, editable by the creator; a unique partial index enforces it.

C9. Detail view storage: separate SVG asset vs viewBox on the parent asset (§7.3 vs audit 04)

Horse_head.svg is a full copy of Horse.svg with a different viewBox and its own overlays (audit 04 §2). §7.2 gives every view its own svg_asset_id. The future editor's "create detail from a zone" naturally produces a view_box on the same asset. Plan assumption: svg_asset_id nullable on detail views; null means "render the parent asset with this view_box". The equine seed may keep two assets to stay byte-faithful to the source files. Q5 asks which.

C10. Edge Functions on self-hosted Supabase (§22.2, §31) on a 1 vCPU / 1 GB VPS (DEPLOY.md)

The current runbook provisions 1 vCPU / 1 GB. A self-hosted Supabase stack (Postgres, GoTrue, PostgREST, Storage, Kong, Studio, edge-runtime, Realtime, imgproxy) needs several GB of RAM and is operationally heavy for one person. Either the VPS is upgraded, or the launch uses managed Supabase from day one (the architecture's "stage 2" contract is the same schema anyway). This changes Step 3 and the deploy runbook. Q2.

C11. Free-plan quota counted on "completed" reports but editing a completed report is allowed 5 days (§1.2)

Consistent, but note the interaction with revisions: a restore of an old revision after the 5-day window is an edit and must be denied for free accounts. The plan treats any write to a completed report as reports.edit_after_free_window after free_edit_until.

C12. SVG sanitization "server-side before becoming available to others" (§15.3) vs direct-to-Storage uploads

Supabase Storage uploads go straight from the browser to the bucket. The sanitizer must therefore run between upload and publication (quarantine prefix + status column + policy), not "on upload". Designed in BACKEND_ARCHITECTURE.md §5; flagged because a naive implementation would ship the client sanitizer as the boundary, which the audit already marks insufficient (F1).

C13. CLAUDE.md rules that the migration necessarily breaks

  • "domain/schema/*.ts are the data contracts, never change without bumping version": honoured (v3).
  • "Ask before any change to importReportFromPdf or extractReportJson": honoured as a confirmation gate in the PDF step.
  • "Never modify anatomy SVGs in public/species/": honoured; the importer reads, never writes them.
  • "Each entry needs ≥1 source with citation": violated today by all 792 nodes (audit 05 §2.4). Either the rule is relaxed for the official seed or sources are authored before publication. Plan assumption: relaxed, sources optional, a warning in the editor.
  • "React SPA exception" (BDR-001): still valid for apps/app; the public site is the SSR part.

C14. Report locale not persisted (BDR-014) vs stored PDF artifacts

Server-stored PDFs must record the locale they were rendered in (artifact metadata), otherwise re-rendering from the snapshot cannot reproduce the document. Not a schema change on the report document; an artifact column.

B. QUESTIONS POUR LE DEVELOPPEUR

Only questions whose answer changes the architecture or the order of work.

Q1. Are there Faunosteo PDFs (report v2) in real use that must import into the SaaS?

  • What: whether practitioners (or the client osteopath) hold exported PDFs today.
  • Why: decides if the v2ToV3 + legacy-id reconciliation path is production code with its own UI (quota, mapping review) or a dev-only adapter kept for regression tests (architecture §23.4 assumes no install base; CHANGELOG 0.1.0 says the same, but faunosteo.com is live per TODO Phase C).
  • How to answer: ask the client; check the live site usage if any analytics exist (none in the repo).

Q2. Hosting target for the first steps: self-hosted Supabase on an upgraded VPS, or managed Supabase?

  • What: RAM/CPU available on the Scaleway VPS, and whether running the full Supabase Docker stack (plus Edge Functions) is acceptable operationally.
  • Why: changes Step 3 (local dev is identical, but the deploy runbook, backups, Edge Function deployment and cost differ), and whether Edge Functions are used at all before the agenda/widget steps.
  • How to answer: DEPLOY.md says 1 vCPU / 1 GB; confirm the plan for the box (free -m, nproc on the VPS) and the budget.

Q3. Must the vertebral model support non-mammalian layouts (birds) in the MVP data model?

  • What: the species list. README cites dog, cat, goat, cow, pig, rabbit, donkey, sheep; TODO Phase D cites "chicken". Birds have fused regions (notarium, synsacrum, pygostyle).
  • Why: with an ordered region list (C1) any mammal fits; birds need fused/variable regions and change the picker. Deciding now avoids a document schema v2 right after launch.
  • How to answer: product decision; the model in this plan (ordered region list with free codes) covers birds if region labels are free, so the answer only affects the picker UI.

Q4. Is public/pathology-editor.html used today by an external domain expert?

  • What: BDR-022 mentions a "domain expert" authoring the catalog; audit 11 could not tell whether the static tool is their workflow.
  • Why: if yes, it must keep working against a JSON export of the official sheet during the editor-merge step and gets a documented export/import bridge; if no, it is deleted with the SVG editor.
  • How to answer: ask the expert; check whether any pathologies-equine-<timestamp>.json exports exist outside the repo.

Q5. Equine seed: two SVG assets (byte-faithful to Horse.svg and Horse_head.svg) or one asset + view_box for the head?

  • What: storage shape of the official sheet v1.
  • Why: affects the sheet document schema (svg_asset_id nullable), the renderer, the PDF detail view, and the "create detail view" editor feature. Two assets keep the files untouched; one asset halves storage and matches the future editor.
  • How to answer: product/technical choice; recommendation is nullable svg_asset_id and two assets for v1 only.

Q6. Report-only manual points and shared client records: where do they live?

  • What: (a) schema and rendering of points created inside a report and not in any sheet (C2); (b) edit rights on global client core fields and whether notes_general is shared (C4).
  • Why: both freeze the report document v3 and the client RLS, which are the two hardest migrations.
  • How to answer: product decision. Recommendation: (a) localAnnotations[] in the report document, rendered in the PDF, promotion creates a new personal-sheet version and rewrites the report to reference it; (b) core identity editable by creator or claimed client only, notes per relationship.

Q7. Phone verification and transactional email providers

  • What: which SMS provider and which email provider (EU processing).
  • Why: phone verification is a sign-up gate (§3.1) and a referral prerequisite; without a provider decision Step 7 ships email-only verification and the referral rules cannot be tested end-to-end.
  • How to answer: business decision; GoTrue supports Twilio, MessageBird, Vonage, Textlocal.

Q8. Public site framework: Next.js (architecture §21.2) or Astro SSR (global rule "Astro by default")?

  • What: the framework of apps/public-web.
  • Why: toolchain, Docker image, SEO tooling for the public-profile step. Does not affect the private app.
  • How to answer: decide at that step; default to Next.js as approved unless the global rule is meant to override.

Q9. Catalog anomalies to normalise or preserve in the official seed

  • What: sphenoid.categories[0].id === 'ssb-dysfunctions' (same id as under ssb), degraded category slugs (charni-res-vert-brales, cadrans-du-cr-ne), zero sources, zero description_en.
  • Why: the importer is deterministic and the seed v1 is immutable once published; renaming later means v2 of the official sheet. Finding paths in future reports anchor on these ids.
  • How to answer: domain expert review of docs/faunosteo-audit/05-findings-editor.md §2.4; recommendation: fix the ssb-dysfunctions id to sphenoid-dysfunctions before v1 (no report references it yet), keep slugs verbatim with human labels.