# Plan 0.0.4 — fondation PostgreSQL partagée ## Statut et sources Release ouverte depuis la stable autoritaire : ```text Knowledge tag v0.0.3 Knowledge commit b3823972449150b72905930b806d4d15471cddce Knowledge SHA-256 82407dc2a83be878daa65692f975681428d0adc721ff249c3c9020e3a9d1f29d publish report sasedev-knowledge-0.0.3-publish.001-report.md = PASS start prompt prompts/004-V0_0_4_START_PROMPT.md ``` Le plan est actif à partir de `0.0.4-alpha.1`. PGR `v0.1.3` reste une provenance historique et aucune adoption PGR nouvelle n'est engagée. ## Mission Matérialiser la première fondation PostgreSQL partagée de Knowledge afin de conserver un état transversal minimal pour les sources et la synchronisation, avec migrations reproductibles et tests PostgreSQL réels, sans déplacer la vérité éditoriale hors de Git. À la clôture de `0.0.4`, le workspace doit posséder un owner PostgreSQL concret et partagé, un premier schéma versionné, un pool/configuration injectables et un chemin persistant pour la dernière révision synchronisée utilisable par l'orchestration applicative. ## État acquis et questions ouvertes Acquis depuis `0.0.3` : - Git générique de lecture et snapshot ; - écriture Git contrôlée et push gardé ; - `knowledge-app-lib` pour la synchronisation provider-neutral ; - trois launchers Web et composition Maud/Vite ; - base PostgreSQL logique partagée déjà retenue par l'architecture ; - horizon produit `0.0.5` à `0.0.10` révisable. Décisions de `alpha.1` : - `tokio-postgres` sélectionné comme driver, `deadpool-postgres` comme pool et Refinery comme migrator, sans ORM ; - `knowledge-store-postgres-lib` retenu comme owner ; - migrations SQL versionnées possédées par la crate ; - premier schéma limité aux sources logiques et à la dernière révision synchronisée ; - test PostgreSQL via URL explicitement fournie et schéma éphémère isolé ; - aucune lecture implicite de secrets par la crate et aucun fallback de stockage. Décisions matérialisées par `alpha.2` : - façade publique minimale `PostgresStoreConfig` / `PostgresStore` / `PostgresStoreError` ; - pool borné par `max_pool_size` sans exposition de types Deadpool ; - versions revalidées `tokio-postgres 0.7.18`, `deadpool-postgres 0.14.2`, Refinery `0.9.2` et Tokio test `1.53.1`, avec features minimales `runtime`, `rt_tokio_1` et `tokio-postgres` respectivement ; - migration `V1__initial_sources.sql` embarquée et appliquée explicitement ; - premier backend sans TLS via `NoTls`, sans dépendance TLS prématurée ; - test réel de migration isolé par schéma et déclenché explicitement par la gate. Questions laissées aux tranches suivantes : - besoin réel d'un contrat passif de persistance dans `knowledge-app-lib` pour le raccord `alpha.4` ; - backend TLS à sélectionner uniquement si le déploiement visé l'exige ; - paramètres supplémentaires de pool uniquement sur besoin runtime observé. ## Scope `0.0.4` couvre : - une crate PostgreSQL partagée réelle ; - `tokio-postgres` PostgreSQL/Tokio avec pool `deadpool-postgres` ; - première migration reproductible ; - persistance de `SourceId`, `ContentFamily`, référence Git logique et dernière révision synchronisée ; - erreurs récupérables sans fuite de credentials ; - tests unitaires ciblés et intégration PostgreSQL réelle ; - raccord applicatif minimal permettant d'utiliser l'état persistant sans modifier le contrat Git ; - documentation durable, beta, RC et fermeture stable. ## Hors scope Restent hors `0.0.4` : - corps/métadonnées éditoriales publiées en PostgreSQL comme vérité ; - modèles de contenu finaux et parsing complet ; - projections finales/indexation détaillée ; - recherche avancée ; - Gitea/forge et webhooks spécifiques ; - scheduler/jobs ; - auth/session/rôles/capabilities ; - propositions/revues/publication produit ; - templates publics/admin et routes finales ; - quatrième application admin ; - rebase/merge automatique ; - partage multi-processus de la racine Git ; - LFS/submodules et rétention avancée. ## Stratégie de validation La validation reste proportionnée à chaque tranche. Les invariants documentaires et Rust continuent d'utiliser : ```text Markdown + hygiène texte cargo fmt --all cargo fmt --all -- --check audits Rust locaux cargo metadata / cargo check Clippy strict tests ciblés puis workspace lorsque le contrat devient transverse git diff --check / git diff --cached --check ``` À partir de la première migration, une gate PostgreSQL réelle devient obligatoire. Elle utilise `KNOWLEDGE_POSTGRES_TEST_URL`, isole chaque exécution dans un schéma temporaire et nettoie cet état après test. Si la tranche requiert cette preuve et qu'aucun PostgreSQL n'est disponible, le statut est `BLOCKED`. Les gates Web/npm ne sont pas rejouées pour les alphas sans diff `Web/` ou contrat Web. Les phases de stabilisation peuvent imposer une non-régression runtime globale. ## Trajectoire prévisionnelle ### alpha.1 — baseline, étude et cadrage - vérifier intégralement `v0.0.3` et `publish.001` ; - relire owners, architecture, deltas/histories, `DEFER` et horizon ; - confirmer l'autonomie normative Knowledge ; - comparer les options PostgreSQL actuelles ; - décider le driver `tokio-postgres`, le pool `deadpool-postgres`, Refinery, l'owner, le schéma, la configuration et la stratégie de test ; - créer l'étude `008`, le présent plan et le delta ; - ne modifier aucun code produit, dépendance ou migration ; - autoriser `alpha.2` seulement après `PASS` opérateur. ### alpha.2 — owner PostgreSQL, pool et première migration - créer `knowledge-store-postgres-lib` avec façade crate-root conforme ; - ajouter uniquement les dépendances/features nécessaires de `tokio-postgres`, `deadpool-postgres`, Refinery et Tokio ; - matérialiser la configuration explicite de connexion/pool et les erreurs publiques sans fuite de secret ; - ajouter `migrations/` sous la crate et la migration initiale `knowledge_sources` + `knowledge_source_sync_state` ; - exposer une opération explicite d'application des migrations ; - prouver la migration sur PostgreSQL réel avec schéma de test isolé ; - ne raccorder encore aucun launcher si aucun use case runtime ne l'exige. ### alpha.3 — persistance de source et état de synchronisation - matérialiser les opérations minimales de création/mise à jour/lecture de configuration logique ; - convertir `ContentFamily`, `SourceId`, référence logique et `GitRevision` sans faire remonter les types PostgreSQL/Deadpool/Refinery au domaine ; - lire et enregistrer `last_synchronized_revision` ; - tester insertion, mise à jour, absence d'état, contraintes et isolation des sources sur PostgreSQL réel ; - prouver qu'aucun corps de contenu ou credential Git n'est persisté par ce schéma. ### alpha.4 — raccord applicatif persistant - conserver `synchronize_repository` comme primitive provider-neutral ; - ajouter seulement le contrat applicatif nécessaire pour charger/enregistrer la révision précédente sans dépendance au driver/pool/migrator dans `knowledge-app-lib` ; - implémenter ce contrat côté `knowledge-store-postgres-lib` ; - composer un cas d'usage persistant qui charge l'état, synchronise via Git et enregistre la révision uniquement après succès ; - tester Changed/Unchanged, première synchronisation et absence d'écriture après erreur Git/store ; - ne pas ajouter scheduler, projection de contenu ou route Web. ### beta.1 — réconciliation et revue d'horizon - réconcilier le schéma, l'API, le lifecycle et les tests réellement obtenus ; - vérifier que Git reste l'autorité du contenu et que le state PostgreSQL est reconstructible ; - préparer `CHANGELOG.md` en `0.0.4 (candidate)` seulement à ce stade ; - réévaluer `0.0.5` modèles/projections et au moins `0.0.6` / `0.0.7` ; - préparer `prompts/005-V0_0_5_START_PROMPT.md` uniquement si la prochaine mission reste suffisamment décidée ; - rejouer les preuves PostgreSQL et non-régression workspace nécessaires à la stabilisation. ### rc.1 — candidate stable - geler le scope ; - rejouer la gate complète Rust/PostgreSQL applicable ; - vérifier migrations depuis un schéma vide, persistance source/state et raccord applicatif ; - vérifier deltas/histories, hors-scope et hygiène de livraison ; - rejouer la non-régression Web/runtime exigée par la phase de stabilisation ; - n'introduire aucune fonctionnalité nouvelle. ### rel.1 — promotion stable pré-tag - promouvoir mécaniquement `VERSION` et workspace vers `0.0.4` ; - finaliser changelog, README, roadmap et plan depuis le résultat réellement acquis ; - vérifier le handoff `0.0.5` seulement s'il a été autorisé par la revue beta ; - rejouer la gate stable complète ; - produire le history observé avant commit stable/tag ; - ne fabriquer aucun rapport post-tag avant publication réelle. ## Déclencheurs de REPLAN REPLAN avant de poursuivre si : - les versions retenues de `tokio-postgres`, `deadpool-postgres` ou Refinery sont incompatibles avec la toolchain stable réellement utilisée ou les lints locaux ; - le premier schéma exige déjà de stocker le corps éditorial publié pour fonctionner ; - une seconde implémentation de store rend une frontière `-api` réellement nécessaire ; - le raccord applicatif crée une dépendance cyclique ou oblige le domaine à dépendre du driver, du pool ou du migrator ; - la stratégie de test par schéma isolé ne peut pas prouver les migrations de manière fiable ; - une connexion PostgreSQL devient une dépendance obligatoire de tous les launchers sans cas d'usage qui la justifie ; - un scheduler, worker ou service réseau supplémentaire devient nécessaire pour fermer la mission ; - une tranche atteint `.fix.3`. La conclusion du REPLAN utilise `CONTINUE`, `SPLIT`, `CONTINUE-NEXT-SESSION` ou `ABANDON`. ## Clôture et transition `0.0.4` est fermable lorsque : - `knowledge-store-postgres-lib` est un owner réel et testé ; - une base PostgreSQL vide peut être migrée de manière reproductible ; - les sources logiques et leur dernière révision synchronisée sont persistées ; - le pool et les erreurs ne fuient aucun secret ; - l'indisponibilité PostgreSQL n'est jamais masquée par un fallback ; - l'orchestration peut utiliser la révision persistée sans coupler le domaine à SQL ; - Git reste l'autorité de toute donnée éditoriale publiée ; - beta/RC ont fermé les non-régressions et l'horizon. À l'ouverture, seule `alpha.1` est matérialisée. Aucun history `0.0.4` n'existe avant la gate opérateur de cette tranche. ## Revue d'horizon L'étude `alpha.1` ne modifie pas l'horizon issu de `0.0.3-beta.1` : ```text 0.0.5 modèles de contenu et projections PGR/HOWTO/snippet 0.0.6 templates publics des trois sites 0.0.7 templates d'administration des trois sites 0.0.8 lecture publique Actix Web / Maud 0.0.9 administration Actix Web / Maud et autorisation 0.0.10 gestion, proposition, revue et publication ``` La revue beta de `0.0.4` devra confirmer ou replanifier au minimum `0.0.5`, `0.0.6` et `0.0.7` à partir de la persistance réellement obtenue.