0.0.2-alpha.1

docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md

@@ -1,5 +1,5 @@
 <!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
-<!-- version: 9 -->
+<!-- version: 10 -->
 
 # Architecture de fondation Knowledge
 
@@ -69,9 +69,9 @@ knowledge-pgr-server     knowledge-howtos-server  knowledge-snippets-server
 
 La dépendance pointe vers les contrats métier. Les détails Actix, processus Git, API Gitea ou SQL ne remontent pas dans le domaine.
 
-`GitRepository` ne porte que les opérations génériques actuellement nécessaires : rafraîchir la vue locale d'une source et résoudre une référence opaque vers une révision Git autoritaire. Le contrat ne suppose ni API de forge, ni type de remote particulier, ni format SHA figé.
+`GitRepository` ne porte dans la stable `0.0.1` que les opérations génériques alors nécessaires : rafraîchir la vue locale d'une source et résoudre une référence opaque vers une révision Git autoritaire. `0.0.2` n'étend ce contrat que lorsqu'un besoin de snapshot réellement implémenté le démontre. Le contrat ne suppose ni API de forge, ni type de remote particulier, ni format SHA figé.
 
-`RepositoryEventSource` ne produit qu'un `RepositorySyncSignal` associé à un `source_id`. La cause est volontairement grossière (`Explicit`, `Periodic`, `ExternalSignal`) afin que hook Git, webhook de forge ou watcher ne deviennent pas des concepts autoritaires du domaine.
+`RepositoryEventSource` ne produit qu'un `RepositorySyncSignal` associé à un `source_id`. La cause reste volontairement grossière (`Explicit`, `Periodic`, `ExternalSignal`) afin que hook Git, webhook de forge ou watcher ne deviennent pas des concepts autoritaires du domaine.
 
 ## 1. Applications publiques
 
@@ -105,32 +105,81 @@ Le domaine ne suppose pas qu'une famille possède exactement un repository. Il m
 
 ## 3. Git générique
 
-Le contrat conceptuel `GitRepository` couvre uniquement les opérations Git nécessaires :
+Le contrat `GitRepository` reste provider-neutral. `0.0.2-alpha.1` sélectionne comme première implémentation un **processus `git` contrôlé** dans la future crate :
 
 ```text
-refs / resolve revision
-fetch
-checkout ou worktree local
-status/diff
-branch
-commit
-merge/rebase contrôlé lorsque le workflow l'exige
-push lorsque autorisé
+knowledge-git-lib
 ```
 
-L'implémentation doit fonctionner sans connaître Gitea, GitHub ou GitLab.
+Cette sélection est une décision locale Knowledge, pas un couplage du contrat au CLI Git. Une autre implémentation pourra remplacer le backend ultérieurement si des preuves de maintenance, performance ou portabilité le justifient.
 
-Le serveur préfère des mirrors/clones et worktrees locaux. Une requête publique ne doit pas déclencher un appel réseau vers la forge.
+### Configuration physique
 
-La baseline prévoit au moins trois sources Git indépendantes :
+`knowledge-domain-lib` continue de posséder `SourceId` et `ContentSource`. Les URLs, chemins locaux, exécutable Git et répertoires de travail ne remontent pas dans le domaine.
+
+`knowledge-git-lib` possédera la configuration physique :
 
 ```text
-pgr       source primaire de knowledge-pgr-server
-howtos    source primaire de knowledge-howtos-server
-snippets  source primaire de knowledge-snippets-server
+source_id -> local path ou remote Git générique
+source_id -> référence cible configurée
+backend   -> racine d'état Git contrôlée
 ```
 
-Ce mapping est configurable et extensible ; il ne devient pas un `match` codé en dur sur trois repositories.
+La composition runtime pourra charger ces valeurs depuis la configuration de déploiement. La persistance logique future dans PostgreSQL reste différée.
+
+### Matérialisation locale
+
+Les données générées résident hors du dépôt applicatif et hors des dépôts éditoriaux :
+
+```text
+<git-state-root>/
+  hooks-disabled/
+  repositories/
+    <source-key>.git/
+  snapshots/
+    <source-key>/
+      <resolved-revision>/
+```
+
+Le backend reçoit explicitement `<git-state-root>` ; il n'utilise aucun défaut implicite sous le workspace. Une variable de déploiement telle que `KNOWLEDGE_GIT_STATE_ROOT` pourra alimenter la composition, mais la librairie reçoit un chemin et ne lit pas elle-même l'environnement.
+
+`source-key` est une clé sûre dérivée par l'implémentation. Un `SourceId` ou une URL remote ne sont jamais interpolés directement comme chemin de filesystem.
+
+Pendant `0.0.2`, une racine d'état appartient exclusivement à une instance backend/processus. Le partage simultané d'une même racine entre plusieurs processus reste `DEFER` jusqu'à matérialisation d'un verrouillage inter-processus.
+
+### Mirror et refresh
+
+Une source locale ou remote converge vers un mirror Git contrôlé.
+
+L'initialisation utilise conceptuellement :
+
+```text
+git clone --mirror [--no-local pour une source locale] -- <source> <mirror>
+```
+
+Pour une source locale, `--no-local` évite de créer une dépendance par hardlinks/optimisation locale sur le repository éditorial.
+
+Le refresh réutilise la configuration du remote du mirror et met les refs à jour avec pruning. L'opération doit être idempotente et ne dépend d'aucune API de forge.
+
+### Résolution et snapshot
+
+Une référence cible n'est jamais considérée comme identité autoritaire avant résolution. Le backend exige qu'elle se résolve vers un commit réel, selon la sémantique :
+
+```text
+git --git-dir=<mirror> rev-parse --verify --end-of-options <reference>^{commit}
+```
+
+La valeur obtenue devient `GitRevision`.
+
+Le snapshot de lecture est ensuite créé comme worktree détaché adressé par cette révision. Un snapshot déjà présent n'est réutilisé qu'après vérification de son `HEAD` et d'un état propre ; une divergence produit une erreur récupérable plutôt qu'un nettoyage destructif silencieux.
+
+Les hooks Git sont désactivés pour les opérations de checkout/worktree appartenant au backend. Les commandes sont exécutées directement sans shell, avec prompts interactifs désactivés et sans journaliser de credential.
+
+### Scope futur du contrat Git
+
+Les opérations génériques à plus long terme peuvent inclure `status/diff`, branch, commit, merge/rebase et push. Elles ne sont pas ajoutées en `0.0.2` : la release n'étend le contrat que pour la matérialisation de lecture réellement nécessaire.
+
+La baseline conserve au moins trois sources indépendantes (`pgr`, `howtos`, `snippets`) mais le mapping reste configurable et extensible ; aucun `match` codé en dur n'impose exactement trois repositories.
 
 ## 4. Forge optionnelle
 
@@ -150,9 +199,9 @@ Gitea est le premier candidat d'intégration mais n'est pas figé comme dépenda
 
 ## 5. Événements et synchronisation
 
-Le contrat conceptuel `RepositoryEventSource` produit un **signal de synchronisation**, pas une vérité de contenu.
+Le contrat `RepositoryEventSource` produit un **signal de synchronisation**, pas une vérité de contenu.
 
-Sources prévues :
+Sources conceptuelles :
 
 ```text
 sync explicite
@@ -162,22 +211,28 @@ webhook de forge
 watcher filesystem éventuel
 ```
 
-Toutes convergent vers le même cas d'usage interne :
+Toutes les sources doivent converger vers le même cas d'usage :
 
 ```text
 signal(source_id)
-  -> fetch/refresh si nécessaire
+  -> refresh du mirror si nécessaire
   -> résolution de la révision cible Git
-  -> comparaison avec la dernière révision indexée
-  -> checkout/worktree de la révision
-  -> parsing + validation selon la famille
-  -> construction d'une projection/index
-  -> publication atomique de l'état dérivé
+  -> comparaison avec previous_revision
+  -> snapshot/worktree de cette révision si changement
+  -> futurs parsing + validation + projection
 ```
 
-Un webhook peut être perdu ou dupliqué. Le commit Git résolu reste l'identité autoritaire de la révision.
+Un webhook peut être perdu ou dupliqué. Le commit Git résolu reste l'identité autoritaire.
 
-La synchronisation peut être déclenchée par chacun des trois serveurs au début. Un worker séparé n'est créé que si un besoin d'ownership/lifecycle distinct apparaît.
+### Ownership de `0.0.2`
+
+La synchronisation partagée est une responsabilité de couche application, distincte du backend Git et des producteurs de signaux. La candidate existante `knowledge-app-lib` devient l'owner naturel si l'orchestration réelle confirme qu'une crate partagée est nécessaire ; elle n'est pas créée en `alpha.1` comme placeholder.
+
+Sans PostgreSQL dans cette release, la dernière révision connue n'est pas stockée dans un fichier ad hoc caché. Le cas d'usage reçoit `previous_revision` de l'appelant et retourne explicitement la révision observée ainsi qu'un résultat `Changed` ou `Unchanged`. La future persistance pourra remplacer cet état appelant sans modifier la frontière Git.
+
+La cause `Periodic` reste supportée par `knowledge-sync-api`, mais `0.0.2-alpha.1` ne désigne pas encore de scheduler concret. Un scheduler n'est matérialisé que si son lifecycle/runtime est démontré ; lorsqu'il existe, il appelle exactement le même cas d'usage que la voie explicite.
+
+La synchronisation peut rester composée par chacun des trois serveurs au début. Un worker réseau séparé n'est créé que si un owner/lifecycle distinct devient nécessaire.
 
 ## 6. Propositions et revues
 
@@ -291,7 +346,7 @@ La fondation matérialisée est cohérente avec les objectifs `0.0.1` :
 - frontend de référence indépendant et rendu runtime Maud effectivement relié au manifest Vite ;
 - aucune persistance PostgreSQL, auth complète, UI admin complète, forge spécifique ou format final HOWTO/snippet introduit par anticipation.
 
-Les prochaines capacités sont donc reprises par releases séparées. `0.0.2` engage uniquement le chemin Git générique de lecture et la synchronisation réelle ; les autres axes restent différés.
+`0.0.2-alpha.1` conserve cette réconciliation comme baseline : la release courante ouvre uniquement le chemin Git générique de lecture et la synchronisation réelle ; les autres axes restent différés.
 
 ## 10. Administration
 
@@ -350,9 +405,9 @@ Une pratique répétée dans HOWTO/snippet peut devenir un candidat d'étude PGR
 - utilisateurs/sessions ;
 - propositions et revue ;
 - commentaires/audit applicatif ;
-- configuration logique des sources ;
+- configuration logique persistante des sources lorsque PostgreSQL sera matérialisé ;
 - mapping source/famille/application ;
-- dernière révision synchronisée/indexée par source ;
+- dernière révision synchronisée/indexée par source lorsque la persistance sera matérialisée ;
 - index et recherche dérivés ;
 - relations calculées entre familles ;
 - jobs de synchronisation/publication ;
@@ -372,3 +427,5 @@ snippets            source Git courte/contextualisée séparée
 ```
 
 Les dépôts de contenu ne sont pas fusionnés dans PGR et ne sont pas requis comme submodules Git du dépôt applicatif. Leur localisation et leurs credentials sont de la configuration de déploiement.
+
+Pendant `0.0.2`, cette configuration de déploiement est adaptée en configuration physique possédée par `knowledge-git-lib`. La racine de mirrors/worktrees reste un état généré reconstructible et ne remplace pas le futur stockage logique PostgreSQL.