docs(docs): db:trial implementation plan and gated contract

This commit is contained in:
bchanot committed 2026-11-10 13:36:14 +01:00
1 parent b682f78209
commit 60087bab30
2 files changed
+3803

No files matched your search

@@ -0,0 +1,262 @@
# CONTRACT — db-trial-stack
- date: 2026-11-09 | flow: ship-feature | branch: feature/v1-2-anatomical-sheets
- status: active
- worktree: /home/bchanot/Documents/faunosteo-v1-2 (every command from this absolute path, LRN-110; never the main
checkout /home/bchanot/Documents/faunosteo, whose old scripts reach DEV). Commit in place on the working branch,
push each commit; no sub-branch, no merge, no `gitflow.sh finish`.
- base: b215b89
- untracked files kept: `faunosteo-v1-2-6-revue-ux-chatgpt.md` (this worktree),
`/home/bchanot/Documents/faunosteo/faunosteo-v1-2-4-revue-chatgpt.md` (main checkout).
- design reference: `docs/development/TRIAL_STACK.md` (arbitrations A11-A15 settled, BDR-107 to BDR-110),
`docs/development/V1-2_ANATOMICAL_SHEETS.md` §5.7.1 (first owner bootstrap order).
## REQUEST (verbatim — IMMUTABLE)
# FAUNOSTEO — Après R0 — Implémentation technique de la pile d'essai dédiée
Le propriétaire prend acte de la clôture graphique de R0, du verdict indépendant CONFORME et de BDR-110.
Les maquettes R0 sont définitivement validées. Ne pas rouvrir leur conception.
## 1. Autorisation
Autorisation ciblée pour implémenter les scripts, configurations et tests nécessaires à la pile d'essai dédiée, selon docs/development/TRIAL_STACK.md et les arbitrages A11 à A15.
Cette autorisation ne couvre PAS le démarrage effectif de la pile ni la création de données.
## 2. Isolation
Créer une pile distincte de la sandbox automatisée et de Supabase DEV :
- Préfixe des conteneurs : faunosteo_trial_.
- Commandes : pnpm db:trial.
- Ports séparés, selon le plan validé.
- Base de données, stockage, secrets, réseaux et volumes distincts.
- Volumes persistants et sauvegardes contrôlées.
- Limites mémoire adaptées aux ressources de l'hôte.
- Aucune réutilisation des volumes, secrets ou noms de conteneurs de DEV ou de la sandbox.
Conserver les commandes db:sandbox trial* existantes, sans redirection implicite.
## 3. Sécurité
Mettre en place des garde-fous empêchant les suites E2E, Vitest ou les outils de réinitialisation de la sandbox d'utiliser la pile d'essai.
Privilégier des vérifications bloquantes : tout environnement ambigu doit provoquer un refus d'exécution.
Ne pas exposer les ports internes de PostgreSQL, Auth ou Storage au réseau local.
Prévoir la rotation des secrets sans perte de données.
Ne jamais écrire de secrets dans Git, les journaux ou les rapports.
## 4. Comptes d'essai
Prévoir deux comptes distincts :
- Owner/admin, pour les essais administratifs.
- Praticien d'essai avec rôle admin technique et habilitation sheet_editor, sans owner, reviewer ou publisher.
Ne pas modifier la règle O1.
Documenter clairement que le second compte ne représente pas encore les autorisations d'un praticien de production.
Préserver les exigences MFA.
## 5. Cheval historique
Préparer une méthode reproductible pour charger la fiche équine de référence et ses illustrations.
Ne pas copier silencieusement des données de la sandbox actuelle.
Vérifier les empreintes, la présence des illustrations et l'intégrité du document importé.
Éviter les doublons en cas de relancement.
Ne pas modifier la fiche équine historique ni les données de DEV.
## 6. Tests
Exécuter uniquement les contrôles ne nécessitant pas de création ou de destruction d'environnement.
Vérifier :
- Le ciblage exclusif des ressources trial.
- Les collisions de ports et de noms.
- Les garde-fous contre les tests automatisés.
- La persistance prévue.
- La sécurité des secrets.
- Les chemins de sauvegarde et de restauration.
- La compatibilité avec les commandes sandbox existantes.
Effectuer une revue indépendante du code et une revue de sécurité.
Commiter et pousser chaque lot validé.
## 7. Checkpoint avant création
Avant de lancer pnpm db:trial up ou une commande équivalente, fournir :
1. La liste exacte des ressources Docker qui seraient créées.
2. Les ports réellement disponibles et les éventuels conflits.
3. L'emplacement des volumes et sauvegardes.
4. Les limites mémoire prévues.
5. Les commandes de démarrage, arrêt, sauvegarde et rotation.
6. La procédure de chargement de l'équin et des illustrations.
7. Les résultats des tests et revues.
8. La preuve que les commandes de test automatiques ne peuvent pas cibler cette pile.
S'arrêter et attendre l'accord explicite du propriétaire avant toute création effective.
## 8. Restrictions
Ne pas démarrer, réinitialiser ou supprimer de conteneur.
Ne pas toucher à la sandbox existante ni à ses 219 fiches.
Ne pas intervenir sur Supabase DEV.
Aucune migration SQL applicative, modification Rust, worker ou format documentaire.
Ne pas commencer R1 à R4, U2, U2b ou V1-2.7.
Aucune fusion ni déploiement.
Préserver les fichiers non suivis, notamment la revue ChatGPT.
S'arrêter au checkpoint de création de la pile d'essai.
## CLARIFICATIONS
Q: backup format and restore? / A: cold physical copy (stack stopped a few seconds, both volumes archived through a
`--rm` helper container, secrets copy, restart) + new command `pnpm db:trial restore <backup>` with typed
confirmation and an automatic backup first; same Postgres image required. Supersedes TRIAL_STACK.md §3.4 `pg_dump -Fc`.
[gated 2026-11-09]
Q: read-only dry run for the checkpoint? / A: new command `pnpm db:trial plan`: exact containers, volumes, network,
each port free or taken, volume and backup locations, memory limits; no docker call that creates or changes anything.
[gated 2026-11-09]
Q: how far to change `scripts/db-sandbox.sh`? / A: guard only (refuse a trial state folder); `db-trial.sh` self-contained
with its own image pins; no shared helper extraction (TRIAL_STACK.md §4 sentence superseded). [gated 2026-11-09]
Q: public sign-up on the trial stack? / A: closed (`GOTRUE_DISABLE_SIGNUP=true`); accounts only through
`pnpm db:trial account`. [gated 2026-11-09]
Q: plan approval? / A: owner 2026-11-10 « Décision sur le plan db:trial »: architecture, lots A, B1, B2, B3, C and
closure approved, conditional on R13 fixed in the plan (exact target identification, no ambiguous destination, no
fallback, db:sandbox trial* preserved with non-regression tests) and an independent targeted counter-check; validated:
exact interactive confirmations, piped or automated confirmations refused, harness outside check:all, grant without
implicit admin, FAUNOSTEO_TRIAL_DIR checked on its canonical path incl. symlinks, no secrets.prev given a restorable
protected prior backup, app address recomputed at each launch, ss checked explicitly. Authorisation covers writing and
static or simulated checks only: no real create/start/stop/migration/restore/destroy/rotation, no DEV or sandbox, no
merge or deploy; a script's interactive confirmation is never the owner's prior authorisation. [gated 2026-11-10]
## ACCEPTANCE CRITERIA
1. `pnpm db:trial` (root `package.json`) runs `scripts/db-trial.sh` with the commands of TRIAL_STACK.md §4 (`create`,
`start`, `stop`, `status`, `migrate`, `backup`, `rotate-keys`, `rotate-secrets`, `app`, `account <email>`,
`grant <email> <right>`, `assets`, `destroy`); `pnpm db:sandbox` keeps every existing command, `trial`,
`trial-account` and `trial-grant` included, with unchanged behaviour (no redirection to the trial stack).
2. Docker resources of the trial stack are literal names only: containers `faunosteo_trial_db`, `_auth`, `_rest`,
`_storage`, `_mail`, `_gateway`, network `faunosteo_trial_net`, volumes `faunosteo_trial_db` and
`faunosteo_trial_storage`; every docker call of `db-trial.sh` that starts, stops, recreates or removes names one of
them (helper containers excepted, prefixed `faunosteo_trial_` and `--rm`), never a filter or a pattern; no name,
port, volume, network or secret is shared with DEV (`supabase_*_faunosteo`, 54321-54324) or the sandbox
(`faunosteo_dbsandbox_*`, 57xxx, 5193).
3. Ports: Postgres 127.0.0.1:58432, GoTrue :58999, PostgREST :58300, Storage :58500, Mailpit :58025, gateway :58801,
all published on 127.0.0.1 only; the app on the validated trial host :5194 (`--strictPort`); every start refuses a
taken port before any docker call and checks after start that each container publishes on 127.0.0.1 only.
4. Persistence: Postgres data in volume `faunosteo_trial_db` at `PGDATA`, Storage files in `faunosteo_trial_storage`
at `/mnt`; restart policy `no`; `start`/`stop`/rotation keep both volumes; a volume is removed only by `destroy`
(and by the restore path if the gate adds one), after a typed confirmation.
5. Resources: per container `--memory`, `--cpus 1`, `--pids-limit` as TRIAL_STACK.md §3.7 (Postgres 1 GiB with
`shared_buffers` 128 MB, PostgREST 384 MiB, Storage 256 MiB, GoTrue 128 MiB, Mailpit and gateway 64 MiB); the app
runs with `NODE_OPTIONS=--max-old-space-size=768`; `create` refuses when the host lacks the memory budget.
6. Secrets: state folder `~/.cache/faunosteo-trial` (override `FAUNOSTEO_TRIAL_DIR`), mode 700, refused inside the
repository and refused when it is (or holds) the sandbox state; files 600; values reach containers and tools through
env files or stdin, never argv, script output, logs or Git; keys signed with the trial's own JWT secret, issuer
distinct from `db-sandbox`, valid one year; `rotate-keys` re-signs both keys, `rotate-secrets` renews JWT secret,
keys and role passwords without data loss, account passwords untouched; neither prints a secret.
7. Isolation guards, blocking and fail-closed: `db-trial.sh` refuses to run when any `SANDBOX_*` variable is set; the
sandbox suites (`packages/supabase/tests/sandbox/stack.ts` and every importer, the shell and LAN Playwright
configs) refuse any target that is not the sandbox's exact container, loopback ports and key issuer before their
first request; `db-sandbox.sh` refuses a state folder that belongs to the trial stack; `e2e:avatar` and
`e2e:sheet-assets` still refuse anything but the sandbox.
8. Accounts: `account <email>` creates a confirmed account through GoTrue's admin API, password at a hidden prompt
(twice, 12 characters min.), never printed; `grant` assigns platform roles `owner` / `admin` only through
`private.assign_platform_role(null, …)` from a JWT-less session after the operator check of §5.7.1 (verified TOTP
factors present) and catalogue rights as the sandbox does; O1 and every migration unchanged; no MFA factor, aal or
session is written by the script; docs state that the practitioner account (technical `admin` + `sheet_editor`) is
not a production practitioner profile.
9. Equine sheet: `create` applies the branch's migrations and `equine_draft.sql` only (never `seed.sql`), after
checking the seed folder's hashes; it then checks in the database that the historical sheet is the only official
sheet and that its draft content equals `document.json`; `assets` uploads the drawings with the existing
`upload-sheet-assets` tool through the trial gateway (no overwrite, rerun = nothing to do) and checks every asset
row uploaded; no data copied from the sandbox; seed files untouched.
10. `migrate` takes a backup first (A15), refuses when a migration already applied differs from its file, applies the
new ones with `--db-url` on 58432 only, and reloads PostgREST's schema.
11. `backup` writes into `<state>/backups/` (700/600, never pruned by the script) what a restore needs, secrets copy
included; the restore path follows the gate's decision.
12. Environment-free checks only (no container, volume or network created, started, stopped or removed during the
run): `shellcheck` clean on the new and changed scripts; a stub harness proves criteria 2-7, 10-11 on the docker
and curl calls the script would make, with no daemon reachable; the guard's unit tests run in `pnpm test:run`;
`pnpm typecheck`, `pnpm lint`, `pnpm test:run` green.
13. Untouched: `supabase/migrations/`, `supabase/seed/`, `crates/`, document and archive formats, DEV, the sandbox's
containers and data, the untracked review files.
14. Docs: `SUPABASE.md` (trial stack section, rotation procedure), `V1-2-6_OWNER_TRIAL.md`, `TRIAL_STACK.md` status,
`CLAUDE.md` commands, `.claude/tasks/TODO.md`.
15. Stop at the creation checkpoint with the 8 items of §7 of the request; no `create` run.
16. [gated 2026-11-10] R13: the trial dev server (`apps/app/vite/trial.config.ts`, shared with `db:sandbox trial`)
serves exactly one of two literal targets (`apps/app/vite/trial-targets.ts`): sandbox = app 5193, gateway
`http://127.0.0.1:57801`, key issuer `db-sandbox`; trial = app 5194, gateway `http://127.0.0.1:58801`, issuer
`faunosteo-trial`, gateway identity `faunosteo_trial`; any other gateway, port, app URL, issuer or role is refused,
no default, no fallback; the exact values `db-sandbox.sh` passes today stay accepted (non-regression tests).
`db-trial.sh` checks before each operation the target container's exact loopback publication, the trial gateway's
identity, and every key it hands over (issuer, role, HMAC with the trial secret, values never in argv). The
independent R13 counter-check returned CONFORME (or every finding it raised is closed in the plan) before lot A2.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm --filter @faunosteo/app exec vitest run tests/unit/vite.trialTargets.test.ts tests/unit/vite.trialConfig.test.ts && pnpm --filter @faunosteo/app exec tsc -p tsconfig.node.json --noEmit && pnpm --filter @faunosteo/supabase exec vitest run tests/sandbox-target.test.ts && echo GUARD-TESTS-OK
EXPECT: GUARD-TESTS-OK
EVIDENCE: pending
17. [gated 2026-11-10] The stub harness passes in full with simulated services only (docker, curl, ss, node and env
wrapped; no daemon reachable), including: typed confirmations of `destroy` (`faunosteo_trial`), `restore`
(`restore <name>`) and `grant` (`grant <role>`) through a terminal only, piped phrases refused; `grant` never adds
`admin` implicitly; `FAUNOSTEO_TRIAL_DIR` refused on its canonical path (symlink into the repository or onto the
sandbox state, any git work tree); `ss` missing or failing refuses (never read as a free port); `rotate-keys` and
`rotate-secrets` take a verified backup first (700/600, checksums, previous `secrets.env` inside); no secret in
any logged argv. bash -n and shellcheck are never offered as proof of real behaviour.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && bash scripts/db-trial-check.sh
EXPECT: db-trial-check: ALL PASS
EVIDENCE: pending
18. [gated 2026-11-10] Static checks: shellcheck clean on `db-trial.sh`, the harness and `db-sandbox.sh`.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && shellcheck scripts/db-trial.sh scripts/db-trial-check.sh && shellcheck -e SC1090,SC1091,SC2016 scripts/db-sandbox.sh && echo SHELLCHECK-OK
EXPECT: SHELLCHECK-OK
EVIDENCE: pending
19. [gated 2026-11-10] Project suites green.
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && pnpm typecheck && pnpm lint && pnpm test:run && echo SUITES-GREEN
EXPECT: SUITES-GREEN
EVIDENCE: pending
20. [gated 2026-11-10] `scripts/db-sandbox.sh` gains lines and loses none since b215b89 (its commands unchanged).
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && test "$(git diff --numstat b215b89 -- scripts/db-sandbox.sh | awk '{print ($1>0 && $2==0) ? "ok" : "bad"}')" = ok && echo SANDBOX-ADDITIONS-ONLY
EXPECT: SANDBOX-ADDITIONS-ONLY
EVIDENCE: pending
21. [gated 2026-11-10] Untouched: migrations, seed and crates (committed and working tree).
CHECK: cd /home/bchanot/Documents/faunosteo-v1-2 && git diff --quiet b215b89 -- supabase/migrations supabase/seed crates && test -z "$(git status --porcelain -- supabase/migrations supabase/seed crates)" && echo UNTOUCHED
EXPECT: UNTOUCHED
EVIDENCE: pending
22. [gated 2026-11-10] Nothing real created: no `faunosteo_trial*` container, volume or network, no state folder
(the pattern is first proven on a fixture line, the listings must succeed).
CHECK: printf 'faunosteo_trial_db\n' | grep -q '^faunosteo_trial' && c=$(docker ps -a --format '{{.Names}}') && v=$(docker volume ls --format '{{.Name}}') && n=$(docker network ls --format '{{.Name}}') && ! printf '%s\n%s\n%s\n' "$c" "$v" "$n" | grep -q '^faunosteo_trial' && test ! -e "$HOME/.cache/faunosteo-trial" && echo NOTHING-CREATED
EXPECT: NOTHING-CREATED
EVIDENCE: pending
23. [gated 2026-11-10] The untracked review files are kept.
CHECK: test -f /home/bchanot/Documents/faunosteo-v1-2/faunosteo-v1-2-6-revue-ux-chatgpt.md && test -f /home/bchanot/Documents/faunosteo/faunosteo-v1-2-4-revue-chatgpt.md && echo REVIEWS-KEPT
EXPECT: REVIEWS-KEPT
EVIDENCE: pending
24. [gated 2026-11-10] Each lot (A, A2, B1, B2, B3, C) tested, reviewed, committed and pushed before the next; no
merge, no deploy, no real create/start/stop/migrate/restore/destroy/rotation, DEV and the sandbox untouched; the
closure report gives the exact R13 counter-check verdict, test results, security review, the 8 checkpoint items
and the read-only `pnpm db:trial plan` output, then stops for the owner's explicit go.
## FILE SCOPE
- new: `scripts/db-trial.sh`, the stub harness under `scripts/`, the guard module and its unit test under
`packages/supabase/tests/`
- changed: `package.json` (one script), `scripts/db-sandbox.sh` (state-folder guard),
`packages/supabase/tests/sandbox/stack.ts`, `apps/app/e2e/playwright.shell.config.ts`,
`apps/app/e2e/playwright.lan.config.ts`, `apps/app/vite/trial.config.ts` (target table checks, R13 [gated
2026-11-10]); new `apps/app/vite/trial-targets.ts`, `apps/app/tests/unit/vite.trialTargets.test.ts` and
`apps/app/tests/unit/vite.trialConfig.test.ts`
- docs: `docs/development/{SUPABASE,V1-2-6_OWNER_TRIAL,TRIAL_STACK}.md`, `CLAUDE.md`, `.claude/tasks/TODO.md`
File diff suppressed because it is too large. Load diff