Sasedev/sasedev-knowledge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.2-alpha.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-28 15:11:03 +02:00
parent 98ec46fe73
commit ab1e5fd652
12 changed files with 1074 additions and 151 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
docs/architecture/001-PROJECT_PROFILE.md
View File

@@ -1,158 +1,185 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 9 -->
<!-- version: 10 -->
# Profil du projet Knowledge
## Baseline autoritaire
Le cadrage initial repose sur :
La stable produit depuis laquelle `0.0.2` est ouverte est :
```text
PGR stable tag v0.1.1
PGR archive SHA-256 caaf8f456f7f8520172ea7705fd0cf5c5bf0e942dc4a773410bcbe7fe4ce243a
PGR publish report pgr-0.1.1-publish.001-report.md = PASS
Knowledge prompt prompts/001-V0_0_1_START_PROMPT.md
Knowledge stable tag v0.0.1
Knowledge stable commit 98ec46fe73bd50dacbe6be220650d87dd2000b74
Knowledge archive SHA-256 1f0b2cfaecee1cbee621abb9c3c95811773ebfc17c374c4369fdc220bcf7d72d
Knowledge publish report sasedev-knowledge-0.0.1-publish.001-report.md = PASS
Knowledge start prompt prompts/002-V0_0_2_START_PROMPT.md
```
L'archive PGR observée possède `VERSION = 0.1.1`, `292` entrées ZIP, `256` fichiers, `36` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Les `48` tests Python et les audits Markdown headers/tables/links de la stable ont été rejoués avant préparation de cette tranche et sont propres.
La fondation `0.0.1` a été construite sous PGR `v0.1.1`. Cette identité reste historique dans les artefacts `0.0.1`.
Cette constatation de prévalidation ne remplace aucune gate opérateur Knowledge.
Le démarrage de `0.0.2` vérifie puis adopte la stable PGR courante :
## Nature de l'instanciation
```text
PGR stable tag v0.1.3
PGR stable commit fe80dbbb737390a7ea99df27d979bd59ccfb86e3
PGR archive SHA-256 f3a7dffd5fe0fd3542e6b5207fda0b94bca2bd05bd5a54542d0a08d635a5d6ee
PGR publish report pgr-0.1.3-publish.001-report.md = PASS
```
Knowledge est un nouveau projet. La procédure normative d'adoption d'un dépôt existant `230-ADOPTION.md` n'est donc pas activée comme owner de migration.
L'archive PGR `v0.1.3` vérifiée possède `VERSION = 0.1.3`, `332` entrées ZIP, `290` fichiers, `42` répertoires, une racine unique `pgr/`, aucun symlink et aucun `.git`. Son rapport post-tag indique `48/48` tests Python et les audits Markdown propres.
Le prompt de démarrage exige néanmoins une matrice `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER`. Les mêmes libellés sont utilisés ci-dessous pour rendre explicite la relation entre PGR et les décisions fondatrices Knowledge :
Cette prévalidation ne remplace aucune gate opérateur Knowledge.
## Nature de l'adoption
Knowledge n'est plus un nouveau dépôt à instancier : `0.0.2-alpha.1` migre un projet existant de la baseline PGR `v0.1.1` vers `v0.1.3`.
L'owner PGR `230-ADOPTION` devient applicable à cette migration ; son contrat est instancié localement par les décisions suivantes :
- partir d'une baseline autoritaire observée ;
- sélectionner uniquement les owners réellement applicables ;
- classifier `ADOPT / KEEP-LOCAL / OVERRIDE / DEFER` ;
- préserver les décisions locales compatibles ;
- ne pas réécrire les commits, deltas, histories ou documents historiques pour simuler une conformité rétroactive ;
- valider proportionnellement la migration.
Les classifications locales restent :
- `ADOPT` — contrat PGR applicable retenu ;
- `KEEP-LOCAL` — choix propre à Knowledge, non possédé par un owner PGR plus spécifique et compatible avec les contrats adoptés ;
- `OVERRIDE` — règle PGR applicable remplacée localement ;
- `KEEP-LOCAL` — choix propre à Knowledge, compatible et non possédé par un owner PGR plus spécifique ;
- `OVERRIDE` — règle PGR applicable remplacée ou raffinée localement avec justification ;
- `DEFER` — choix volontairement reporté avec condition de reprise.
## Owners et skeletons applicables
| Élément | Décision | Matérialisation | Motif |
|----------------------------------------------|---------------------------------|-----------------|----------------------------------------------|
| `200-GOVERNANCE` | `ADOPT` | `alpha.1` | lifecycle/version locale |
| `210-WORKFLOW` | `ADOPT` | `alpha.1` | plan/delta/history/handoff |
| `220-SKELETONS` | `ADOPT` pour l'instanciation | `alpha.1` | composition explicite sans copie mécanique |
| `300-DOCUMENTATION` | `ADOPT` | `alpha.1` | rôles documentaires et taxonomie utile |
| `400-VALIDATION` | `ADOPT` | `alpha.1` | preuves proportionnées et autorité opérateur |
| `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | `alpha.2+` | backend Rust/workspace Cargo contrôlé |
| `530-TYPESCRIPT` | `ADOPT` | `alpha.4` | frontend durable TypeScript |
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | `alpha.4` | package manager/lockfile/scripts explicites |
| `550-VITE` | `ADOPT` puisque Vite est retenu | `alpha.4` | dev server/build/cache/outputs |
| `560-CSS_SASS` | `ADOPT` | `alpha.4` | CSS/Sass et outputs |
| `700-FRAMEWORKS` | `ADOPT` | `alpha.5` | cadre générique des frameworks |
| `710-TAURI` | `DEFER` / non applicable | hors `0.0.1` | aucun host desktop/mobile Tauri |
| skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` | `alpha.1` | fondation locale PGR |
| skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` | `alpha.2` | workspace Rust contrôlé |
| skeleton `003-WEB_FRONTEND` | `ADOPT` | `alpha.4` | frontend indépendant du host |
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | `alpha.4+` | restore/typecheck/build/smoke proportionnés |
| Élément | Décision courante | État Knowledge | Motif |
|----------------------------------------------|------------------------------------|-----------------|---------------------------------------------------------------|
| `200-GOVERNANCE` | `ADOPT` | actif | lifecycle/version locale |
| `210-WORKFLOW` | `ADOPT` | actif | plan/delta/history/handoff |
| `220-SKELETONS` | `ADOPT` comme référence | actif | les skeletons existants ne sont pas réappliqués mécaniquement |
| `230-ADOPTION` | `ADOPT` | `0.0.2-alpha.1` | migration explicite PGR `v0.1.1 -> v0.1.3` |
| `300-DOCUMENTATION` | `ADOPT` | actif | rôles documentaires et taxonomie |
| `400-VALIDATION` | `ADOPT` | actif | preuves proportionnées et autorité opérateur |
| `500-LANGUAGES` + `510-RUST_CARGO` | `ADOPT` | actif | backend Rust/workspace Cargo strict |
| `530-TYPESCRIPT` | `ADOPT` | actif | frontend durable TypeScript |
| `540-JAVASCRIPT_PACKAGE_ECOSYSTEM` | `ADOPT` | actif | npm/lockfile/scripts explicites |
| `550-VITE` | `ADOPT` | actif | dev server/build/cache/outputs/manifest |
| `560-CSS_SASS` | `ADOPT` | actif | CSS/Sass et outputs |
| `700-FRAMEWORKS` | `ADOPT` | actif | cadre générique des frameworks |
| `710-TAURI` | `DEFER` / non applicable | inchangé | aucun host desktop/mobile Tauri |
| skeleton `001-PROJECT_GOVERNANCE_FOUNDATION` | `ADOPT` comme référence historique | matérialisé | fondation locale existante |
| skeleton `002-RUST_CARGO_WORKSPACE` | `ADOPT` comme référence historique | matérialisé | workspace Rust existant |
| skeleton `003-WEB_FRONTEND` | `ADOPT` comme référence historique | matérialisé | frontend indépendant du host |
| validation `005-WEB_FRONTEND_VALIDATION` | `ADOPT` | actif | restore/typecheck/build/smoke proportionnés |
Les profils Java/Maven/Gradle, Android et autres technologies absentes ne sont pas sélectionnés.
Les owners Java/Maven/Gradle restructurés dans PGR `0.1.2`, le profil Android réévalué en `0.1.3` et les autres technologies absentes ne sont pas sélectionnés. Leur évolution n'entraîne donc aucune migration de code Knowledge.
Aucun `OVERRIDE` n'est requis par l'adoption `v0.1.3`.
## Matrice des décisions importantes
| Décision | Classification | Contrat retenu / condition de reprise |
|----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------------|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/polling constituent le socle ; hooks/webhooks sont des accélérateurs |
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée pour l'état transversal et les projections ; jamais vérité du contenu Git publié |
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo ; actif depuis `alpha.2` |
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; les manifests Cargo restent le contrat versionné |
| Actix Web | `KEEP-LOCAL` | trois launchers matérialisés en `alpha.5` et composition partagée dans `knowledge-web-lib` |
| Maud | `KEEP-LOCAL` | rendu SSR commun matérialisé dans `knowledge-web-lib` en `alpha.5` |
| TypeScript | `ADOPT` | conforme au owner `530` et à l'intention locale |
| Package manager frontend | `KEEP-LOCAL` | npm sélectionné en `alpha.4` ; `package-lock.json` versionné |
| Vite | `KEEP-LOCAL` + owner `550` adopté | build/preview des templates et assets de référence ; manifest de production consommé par l’intégration Maud |
| Sass | `KEEP-LOCAL` + owner `560` adopté | styles source de la chaîne de validation Web et des assets réellement servis par les pages Maud |
| Bootstrap | `KEEP-LOCAL` | framework CSS retenu pour les templates de référence et le rendu Maud ; jamais règle PGR universelle |
| Racine(s) frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` pour les références statiques et assets communs |
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; le markup runtime est adapté et servi par Maud |
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` en `alpha.5`, avec dev-origin/manifest/base-path configurables |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le choix de driver/tooling et le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif ; réévaluer sur besoin mesuré |
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte encore différée |
| Quatrième application d'administration | `DEFER` | peut agréger du transverse plus tard mais ne remplace jamais les frontières admin locales |
| Modèle rôles/capabilities | `DEFER` | séparer identité partagée et autorisations métier avant de figer enums/scopes |
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel ; ne pas figer un schéma sans contenu représentatif |
| Noms définitifs de toutes les crates | `DEFER` | seules les responsabilités et les trois launchers sont cadrés ; créer une crate uniquement avec ownership réel |
Aucun `OVERRIDE` n'est requis à ce stade.
La sélection Web `alpha.4` conserve une seule baseline partagée tant qu'aucune divergence réelle entre les trois façades ne justifie plusieurs packages. Les entrées spécifiques pourront être ajoutées dans ce package avant toute duplication de toolchain.
| Décision | Classification | Contrat retenu / condition de reprise |
|----------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------------------------|
| Dépôt applicatif | `KEEP-LOCAL` | `sasedev-knowledge` ; workspace unique de la plateforme |
| Nom court / préfixe crates | `KEEP-LOCAL` | `knowledge` / `knowledge-` |
| Dépôt normatif | `KEEP-LOCAL` | dépôt existant `pgr`, jamais fusionné dans le dépôt applicatif |
| Dépôt HOWTO | `KEEP-LOCAL` | dépôt séparé `howtos` |
| Dépôt snippets | `KEEP-LOCAL` | dépôt séparé `snippets` |
| Nombre de sources Git | `KEEP-LOCAL` | au moins trois sources initiales, sans limite codée à trois |
| Git comme backend du contenu | `KEEP-LOCAL` | invariant d'architecture Knowledge |
| Implémentation Git de `0.0.2` | `KEEP-LOCAL` | processus `git` contrôlé derrière `knowledge-git-api` ; décision réévaluable derrière le contrat |
| Configuration physique Git | `KEEP-LOCAL` | future `knowledge-git-lib` ; source locale/remote + racine d'état ; pas dans le domaine |
| Copies Git générées | `KEEP-LOCAL` | racine d'état explicite hors dépôt source, mirrors et snapshots adressés par clé sûre/révision |
| Partage du cache Git entre processus | `DEFER` | état root exclusif à une instance backend en `0.0.2` ; reprendre avec verrouillage inter-processus réel |
| Forge | `KEEP-LOCAL` | capacité optionnelle derrière adapter ; aucune API de forge dans le domaine |
| Gitea | `DEFER` | premier adapter candidat ; reprendre lorsque des capacités forge-only sont implémentées |
| Synchronisation sans webhook | `KEEP-LOCAL` | explicite/périodique convergent vers le même cas d'usage ; hooks/webhooks restent accélérateurs |
| Scheduler périodique concret | `DEFER` | créer seulement lorsque son owner runtime/lifecycle est démontré |
| Dernière révision observée en `0.0.2` | `KEEP-LOCAL` | fournie par l'appelant et retournée par le cas d'usage ; pas de pseudo-persistance locale |
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée future pour état transversal/projections ; jamais vérité du contenu Git publié |
| Rust stable / édition 2024 | `ADOPT` | profil Rust/Cargo PGR |
| Workspace Cargo | `ADOPT` | skeleton Rust/Cargo déjà matérialisé |
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; manifests Cargo versionnés |
| Actix Web | `KEEP-LOCAL` | trois launchers existants et composition partagée dans `knowledge-web-lib` |
| Maud | `KEEP-LOCAL` | rendu SSR commun dans `knowledge-web-lib` |
| TypeScript | `ADOPT` | owner `530` |
| Package manager frontend | `KEEP-LOCAL` | npm ; `package-lock.json` versionné |
| Vite | `KEEP-LOCAL` + owner `550` adopté | build/preview de références et manifest consommé par Maud |
| Sass | `KEEP-LOCAL` + owner `560` adopté | styles source et assets réellement servis |
| Bootstrap | `KEEP-LOCAL` | framework CSS local Knowledge, jamais règle PGR universelle |
| Racine frontend | `KEEP-LOCAL` | package partagé `Web/knowledge-template-lab/` |
| Templates statiques Web | `KEEP-LOCAL` | harness de conception/validation ; rendu runtime Maud |
| Intégration manifest Vite / Maud | `KEEP-LOCAL` | matérialisée dans `knowledge-web-lib` |
| Driver/ORM PostgreSQL | `DEFER` | reprendre à la première implémentation persistante réelle |
| Migrations PostgreSQL | `DEFER` | reprendre avec le premier schéma réel |
| Moteur de recherche | `DEFER` | commencer par capacités PostgreSQL/index applicatif lorsque ce scope sera engagé |
| Fournisseur d'auth externe | `DEFER` | reprendre lorsque le workflow utilisateur l'exige |
| Surface admin par application | `KEEP-LOCAL` | chaque serveur protège ses opérations privilégiées ; URL exacte différée |
| Quatrième application d'administration | `DEFER` | agréger seulement si une responsabilité transverse apparaît |
| Modèle rôles/capabilities | `DEFER` | reprendre avec les cas d'usage d'autorisation réels |
| Formats finaux HOWTO/snippet | `DEFER` | définir avec corpus réel |
| Autres noms de crates | `DEFER` | créer uniquement lorsque l'ownership est démontré |
## Nomenclature de crates
Les trois packages exécutables sont des boundaries produit retenus :
Les packages matérialisés dans la stable `0.0.1` sont :
```text
knowledge-pgr-server launcher Actix Web de la façade PGR
knowledge-howtos-server launcher Actix Web de la façade HOWTOs
knowledge-snippets-server launcher Actix Web de la façade snippets
knowledge-domain-lib types métier stables de famille/source
knowledge-git-api contrat passif GitRepository provider-neutral
knowledge-sync-api contrat passif RepositoryEventSource
knowledge-web-lib composition Actix/Maud/Vite partagée
knowledge-pgr-server launcher PGR mince
knowledge-howtos-server launcher HOWTOs mince
knowledge-snippets-server launcher snippets mince
```
Ils sont matérialisés depuis `alpha.5`. Leurs `main.rs` restent minces et délèguent à `knowledge-web-lib`. Chacun conserve le contrat de pouvoir protéger sa propre surface d'administration métier lorsque cette surface sera implémentée.
Les responsabilités matérialisées sont :
`0.0.2-alpha.1` ferme deux décisions d'ownership sans créer de placeholder :
```text
knowledge-domain-lib types métier stables de famille/source ; aucune dépendance Actix/Git-provider/forge/PostgreSQL
knowledge-git-api contrat passif GitRepository ; implémentations génériques remplaçables derrière cette frontière
knowledge-sync-api contrat passif RepositoryEventSource et signaux de réconciliation ; plusieurs mécanismes producteurs prévus
knowledge-web-lib composition Actix/Maud partagée, résolution Vite dev/manifest et service des assets
knowledge-pgr-server launcher PGR mince
knowledge-howtos-server launcher HOWTOs mince
knowledge-snippets-server launcher snippets mince
knowledge-git-lib implémentation Git générique + configuration physique + état local contrôlé
knowledge-app-lib owner candidat du cas d'usage de synchronisation partagé, à matérialiser seulement quand l'orchestration réelle le démontre
```
Les responsabilités suivantes restent candidates et ne deviennent des packages que lorsqu'elles possèdent un ownership réel :
Les responsabilités suivantes restent candidates et non matérialisées :
```text
knowledge-app-lib orchestration des use cases transversaux, si la séparation apporte une valeur réelle
knowledge-git-lib implémentation Git générique de knowledge-git-api
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
knowledge-forge-gitea-lib adapter Gitea optionnel
knowledge-logging-lib diagnostics partagés, seulement lorsque plusieurs runtimes en ont effectivement besoin
knowledge-logging-lib diagnostics partagés, seulement sur besoin multi-runtime réel
```
Règles de création :
- ne pas créer une crate uniquement pour refléter un diagramme ;
- ne pas utiliser `-api` sans frontière de contrat indépendante réellement nécessaire ;
- garder le domaine indépendant d'Actix, Gitea et PostgreSQL ;
- garder les adapters dépendants des contrats, jamais l'inverse ;
- garder le domaine indépendant d'Actix, Gitea, Git process et PostgreSQL ;
- garder les adapters/implémentations dépendants des contrats, jamais l'inverse ;
- ne pas dupliquer dans les trois serveurs une logique qui possède clairement un owner commun ;
- ne pas créer un service réseau supplémentaire lorsqu'une crate partagée suffit.
## Corpus auth/admin étudié en alpha.2
## Corpus auth/admin étudié en 0.0.1
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` sont des sources d'inspiration non autoritaires. Leur analyse est conservée dans [`../studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](../studies/001-AUTH_ADMIN_CORPUS_STUDY.md).
Les archives historiques `actix-auth-app-master.zip` et `amahil-project-master.zip` restent des sources d'inspiration non autoritaires. Leur analyse est conservée dans [`../studies/001-AUTH_ADMIN_CORPUS_STUDY.md`](../studies/001-AUTH_ADMIN_CORPUS_STUDY.md).
Elles justifient de conserver séparées :
Elles justifient de conserver séparées l'identité/authentification partagée, l'autorisation privilégiée propre à chaque application et une éventuelle façade transverse ultérieure. Elles ne justifient toujours pas de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA pendant `0.0.2`.
- l'identité/authentification partagée de plateforme ;
- l'autorisation privilégiée propre aux cas d'usage de chaque application ;
- une éventuelle façade d'administration transversale ultérieure.
## Résultat de l'adoption PGR 0.1.3
Elles ne justifient pas encore de créer une crate auth, de figer `/admin` ou `/login`, ni d'adopter OAuth2/OIDC/MFA comme scope `0.0.1`.
L'adoption est bornée aux évolutions réellement applicables :
- `230-ADOPTION` devient applicable parce que Knowledge est désormais un projet existant ;
- les owners déjà adoptés restent actifs ;
- les changements PGR Java/Maven/Gradle/Android ne s'appliquent pas ;
- le `DEFER` Tauri reste inchangé ;
- les skeletons servent de références de comparaison et ne sont pas réinstanciés ;
- les anciennes gates/deltas/histories `0.0.1` conservent leur contexte historique, y compris les états `FAIL` et anciennes décisions corrigées plus tard ;
- aucune règle produit Git/process n'est promue en règle PGR générale.
## Décisions à rouvrir
La réconciliation `beta.1` confirme que les `DEFER` suivants restent légitimes : adapter Gitea, driver/migrations PostgreSQL, moteur de recherche, fournisseur d'identité externe, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet et noms de crates non encore possédés par une responsabilité réelle.
La release `0.0.2` rouvre uniquement l'implémentation Git générique et la synchronisation réelle de lecture.
La prochaine release engagée `0.0.2` rouvre uniquement l'implémentation Git générique et la synchronisation réelle de lecture. Elle ne lève aucun des `DEFER` ci-dessus par elle-même.
Restent différés : adapter Gitea, PostgreSQL/migrations, moteur de recherche, auth/admin complète, quatrième application d'administration, modèle détaillé rôles/capabilities, formats finaux HOWTO/snippet, écriture/publication Git et partage concurrent de la même racine Git entre plusieurs processus.
Un changement de scope produit, l'ajout d'un host natif ou une contrainte externe peut déclencher un REPLAN ; il ne justifie pas un choix anticipé.
Un changement de scope produit, un besoin mesuré ou une contrainte d'exploitation peut déclencher un REPLAN ; il ne justifie pas un choix anticipé.

123
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
View File

@@ -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.