sasedev-knowledge/docs/plans/004-V0_0_4_POSTGRES_FOUNDATION_PLAN.md

Plan 0.0.4 — fondation PostgreSQL partagée

Statut et sources

Release ouverte depuis la stable autoritaire :

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 :

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.2.fix.1 — documentation de la crate de test PostgreSQL

• conserver alpha.2 historisée FAIL à cause de Clippy strict ;
• ajouter uniquement la documentation de crate manquante dans tests/postgres_migration.rs ;
• ne modifier ni le code produit, ni le schéma, ni les dépendances, ni la façade publique ;
• rejouer Clippy strict, les tests Rust et la preuve PostgreSQL réelle ;
• autoriser alpha.3 uniquement après PASS complet du fix.

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 :

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.