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

0.0.2-beta.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-29 06:10:29 +02:00
parent da5445354e
commit 5cee2a65b0
13 changed files with 541 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 7 -->
<!-- version: 8 -->
# Documentation SaseDev Knowledge
@@ -30,6 +30,7 @@
- [`studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md`](studies/002-ACTIX_MAUD_VITE_CORPUS_STUDY.md) — analyse du pattern Vite manifest / Actix / Maud de `actix-auth-app` et contrat de reprise ciblée pour Knowledge.
- [`studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md`](studies/003-V0_0_1_FOUNDATION_RECONCILIATION.md) — réconciliation beta de la fondation, DEFER conservés et revue d'horizon engageant uniquement `0.0.2`.
- [`studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md`](studies/004-V0_0_2_GIT_IMPLEMENTATION_STUDY.md) — étude comparative Git de démarrage `0.0.2`, décision process et ownership du backend.
- [`studies/005-V0_0_2_GIT_SYNC_RECONCILIATION.md`](studies/005-V0_0_2_GIT_SYNC_RECONCILIATION.md) — réconciliation beta du chemin Git/synchronisation, `DEFER` conservés et revue d'horizon sans prochaine release réservée.
## Plans

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 15 -->
<!-- version: 16 -->
# Profil du projet Knowledge
@@ -166,10 +166,10 @@ Elles justifient de conserver séparées l'identité/authentification partagée,
- une nouvelle stable PGR n'a aucun effet tant qu'une réévaluation n'est pas explicitement planifiée ;
- les artefacts historiques `0.0.1` et les tranches antérieures de `0.0.2` restent inchangés.
## Décisions à rouvrir
## Réconciliation beta et décisions différées
La release `0.0.2` rouvre uniquement l'implémentation Git générique et la synchronisation réelle de lecture.
`0.0.2-beta.1` confirme que le scope alpha est matérialisé par neuf packages Cargo : contrats domaine/Git/synchronisation, backend Git générique, orchestration application partagée, composition Web et trois launchers. Aucune responsabilité supplémentaire n'est nécessaire pour fermer la mission de lecture/synchronisation de `0.0.2`.
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.
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, scheduler concret, support explicite submodules/LFS, politique de nettoyage/rétention des snapshots et partage concurrent de la même racine Git entre plusieurs processus.
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é.
La revue d'horizon beta ne réserve aucune release suivante. Un changement de scope produit, un besoin mesuré ou une contrainte d'exploitation pourra engager ultérieurement une nouvelle mission ; il ne justifie pas un choix anticipé.

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
<!-- version: 13 -->
<!-- version: 14 -->
# Architecture de fondation Knowledge
@@ -15,23 +15,25 @@ Le principe directeur reste :
## Workspace Rust matérialisé
`alpha.2` instancie le skeleton PGR `002-RUST_CARGO_WORKSPACE`. `alpha.3` matérialise les trois premières frontières passives :
```text
knowledge-domain-lib famille/source de contenu
knowledge-git-api GitRepository provider-neutral
knowledge-sync-api RepositoryEventSource et signal de réconciliation
```
`alpha.5` complète la fondation avec :
La stable `0.0.1` a matérialisé les premières frontières et le runtime Web :
```text
knowledge-domain-lib famille/source de contenu
knowledge-git-api GitRepository provider-neutral
knowledge-sync-api RepositoryEventSource et signal de réconciliation
knowledge-web-lib composition Actix/Maud et assets Vite
knowledge-pgr-server launcher PGR
knowledge-howtos-server launcher HOWTOs
knowledge-snippets-server launcher snippets
```
`0.0.2` ajoute deux owners réels sans changer la topologie multi-app :
```text
knowledge-git-lib backend Git générique : mirror/refresh/resolve/snapshot
knowledge-app-lib cas d'usage partagé de synchronisation Changed/Unchanged
```
Les deux crates `-api` sont justifiées par des implémentations réellement remplaçables ou multiples. Elles restent sans runtime, sans logging propre et sans dépendance à Actix, Gitea ou PostgreSQL.
Les tests unitaires Rust sont désormais placés hors de `src/` sous `unit_tests/`, conformément à la convention locale Knowledge sélectionnée sur l'option permise par PGR.
@@ -330,9 +332,9 @@ En particulier, Knowledge ne doit pas hériter mécaniquement :
- d’une arborescence d’assets spécifique au corpus ;
- de dépendances TypeScript `@types/*` non justifiées par les packages réellement consommés.
`alpha.4` possède le frontend indépendant et la production du manifest. La clé stable `src/main.ts` constitue l'entrée d'asset commune de départ ; son entrée de manifest doit référencer les sorties JavaScript et CSS générées.
`0.0.1-alpha.4` possède le frontend indépendant et la production du manifest. La clé stable `src/main.ts` constitue l'entrée d'asset commune de départ ; son entrée de manifest doit référencer les sorties JavaScript et CSS générées.
`alpha.5` matérialise `knowledge-web-lib` comme owner partagé de l'intégration Actix/Maud. La crate choisit entre un dev server configuré par `KNOWLEDGE_VITE_DEV_ORIGIN` et un manifest configuré par `KNOWLEDGE_VITE_MANIFEST_PATH`. En production elle dérive le répertoire `assets/` depuis le manifest et le sert sous le préfixe `/assets`, tandis que `KNOWLEDGE_ASSET_BASE_PATH` garde le préfixe d'URL configurable. Les erreurs de configuration/manifest restent récupérables et remontent avant le démarrage du listener.
`0.0.1-alpha.5` matérialise `knowledge-web-lib` comme owner partagé de l'intégration Actix/Maud. La crate choisit entre un dev server configuré par `KNOWLEDGE_VITE_DEV_ORIGIN` et un manifest configuré par `KNOWLEDGE_VITE_MANIFEST_PATH`. En production elle dérive le répertoire `assets/` depuis le manifest et le sert sous le préfixe `/assets`, tandis que `KNOWLEDGE_ASSET_BASE_PATH` garde le préfixe d'URL configurable. Les erreurs de configuration/manifest restent récupérables et remontent avant le démarrage du listener.
Les trois packages `knowledge-pgr-server`, `knowledge-howtos-server` et `knowledge-snippets-server` sont des launchers minces : chacun sélectionne `ServerSite` et le nom de sa variable de bind, puis délègue au runtime commun. Ils ne possèdent aucune logique de rendu ou de manifest dupliquée.
@@ -348,6 +350,21 @@ La fondation matérialisée est cohérente avec les objectifs `0.0.1` :
`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.
## Réconciliation `0.0.2-beta.1`
La mission Git/synchronisation est réconciliée avec l'implémentation réellement obtenue :
- neuf packages Cargo, sans crate placeholder ;
- `knowledge-git-api` provider-neutral et `knowledge-git-lib` comme implémentation process Git contrôlée ;
- sources locales/remotes convergeant vers un mirror contrôlé puis vers une révision commit et un snapshot validé ;
- `knowledge-app-lib` comme unique owner du cas d'usage refresh / resolve / compare / snapshot ;
- dernière révision fournie par l'appelant, sans stockage caché ;
- causes de synchronisation non autoritaires, `Periodic` sans scheduler imposé ;
- règles Knowledge autonomes après l'adoption ponctuelle PGR `v0.1.3` ;
- aucun adapter forge, PostgreSQL, auth/admin complète, écriture Git ou format final HOWTO/snippet introduit par anticipation.
Les besoins de rétention de snapshots, submodules/LFS, partage multi-processus de la racine Git et scheduler concret restent différés jusqu'à preuve d'un besoin réel. Aucune prochaine release n'est numérotée par cette réconciliation.
## 10. Administration
L'administration Web est une interface vers les mêmes cas d'usage que l'édition locale Git, pas une deuxième source de vérité.

39
docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/002-V0_0_2_GIT_SYNC_PLAN.md -->
<!-- version: 10 -->
<!-- version: 11 -->
# Plan 0.0.2 — Git générique et synchronisation de lecture
@@ -28,7 +28,7 @@ PGR publish report pgr-0.1.3-publish.001-report.md = PASS
Le passage de PGR `v0.1.1` à `v0.1.3` est traité comme adoption d'un projet existant via `230-ADOPTION`. Les artefacts historiques de `0.0.1` ne sont pas réécrits. `v0.1.3` constitue une provenance d'adoption, pas une dépendance normative vivante : les futurs démarrages Knowledge doivent partir des règles locales et ne consultent PGR que lorsqu'une nouvelle adoption est explicitement engagée.
`0.0.2-alpha.1` est `FAIL` pour défaut de structure du présent plan malgré des contrôles techniques propres. `alpha.1.fix.1` a corrigé uniquement ce cadrage documentaire et sa gate opérateur est `PASS`. `alpha.2` a été fermée par `alpha.2.fix.2` `PASS`. `alpha.3` démontre le chemin Git réel mais sa gate est `FAIL` sur hygiène/formatage/documentation de test ; `alpha.3.fix.1` corrige ces défauts et enregistre le REPLAN décrit ci-dessous.
`0.0.2-alpha.1` est `FAIL` pour défaut de structure du présent plan malgré des contrôles techniques propres. `alpha.1.fix.1` a corrigé uniquement ce cadrage documentaire et sa gate opérateur est `PASS`. `alpha.2` a été fermée par `alpha.2.fix.2` `PASS`. `alpha.3` a été fermée par `alpha.3.fix.1` `PASS`. `alpha.4` a été fermée par `alpha.4.fix.1` `PASS`, terminant l'adoption PGR comme migration ponctuelle. `alpha.5` est `PASS` et ferme le scope fonctionnel alpha avec `knowledge-app-lib` et le cas d'usage partagé `Changed` / `Unchanged`. `beta.1` est la tranche courante de réconciliation et revue d'horizon.
## Mission
@@ -62,12 +62,12 @@ Décisions déjà matérialisées par le cadrage `alpha.1` et non remises en cau
- la racine d'état reste exclusive à une instance/processus pour `0.0.2` ;
- la révision précédemment observée reste fournie par l'appelant tant que la persistance PostgreSQL est hors scope ;
- `gix` et `git2` restent des alternatives différées, pas des backends ajoutés par symétrie.
- `knowledge-app-lib` est matérialisée en `alpha.5` comme owner du cas d'usage partagé refresh / résolution / comparaison / snapshot.
Questions laissées ouvertes jusqu'à la tranche qui les consomme :
- politique de nettoyage/rétention des snapshots ;
- besoin réel de supporter submodules ou Git LFS dans cette release ;
- besoin réel d'une crate `knowledge-app-lib` pour l'orchestration partagée ;
- mécanisme concret de scheduler périodique, volontairement non requis pour prouver le cas d'usage de synchronisation ;
- prochaine mission/version après `0.0.2`, à décider uniquement lors de la revue d'horizon.
@@ -234,17 +234,20 @@ La gate Rust applique désormais explicitement `cargo fmt --all`, puis `cargo fm
### beta.1 — réconciliation et revue d'horizon
Réconcilier le plan avec l'implémentation réellement obtenue :
Tranche courante de stabilisation. Elle n'ajoute aucune grande fonctionnalité.
- inventorier les contrats et crates effectivement matérialisés ;
- vérifier les `DEFER` et hors-scope ;
- retirer ou corriger les hypothèses de forecast devenues fausses ;
- vérifier l'absence de dépendance forge/PostgreSQL/auth/admin ;
- rejouer les gates Rust/Git et la non-régression Web utile ;
- décider si une prochaine mission est suffisamment claire pour engager une version suivante ;
- ne réserver aucun numéro futur par défaut.
La réconciliation doit :
Aucune grande fonctionnalité nouvelle n'entre en beta.
- inventorier les neuf packages et contrats effectivement matérialisés ;
- confirmer `knowledge-git-lib` comme backend Git et `knowledge-app-lib` comme owner du cas d'usage partagé ;
- vérifier les `DEFER` et hors-scope encore valides ;
- corriger les formulations durables héritées de `0.0.1` qui utilisent encore des numéros d'alpha non qualifiés ;
- confirmer l'absence de dépendance forge/PostgreSQL/auth/admin et d'écriture Git ;
- rejouer la gate Rust/Git et la non-régression Web utile ;
- produire une étude de réconciliation durable ;
- réaliser la revue d'horizon sans réserver de numéro futur par défaut.
Résultat de revue proposé et soumis à la gate beta : aucune prochaine mission n'est suffisamment décidée pour engager une version postérieure à `0.0.2`. Les domaines futurs restent non numérotés.
### rc.1 — candidate stable
@@ -306,14 +309,10 @@ Un REPLAN modifie le présent plan de manière explicite ; il ne doit pas être
## Revue d'horizon
État courant : **non réalisée**.
État courant : **réalisée dans `0.0.2-beta.1` et soumise à validation opérateur**.
Aucune version postérieure à `0.0.2` n'est réservée par le présent plan.
Résultat : aucune version postérieure à `0.0.2` n'est réservée. Les domaines futurs restent non numérotés parce qu'aucune mission suivante ne possède encore un scope et un ordre suffisamment décidés.
La revue appartient à `beta.1` et doit s'appuyer sur le backend Git réellement éprouvé, les DEFER encore ouverts et les besoins produit observés. Elle peut :
Les besoins différés confirmés incluent notamment : PostgreSQL/migrations, parsing/index, propositions/admin/auth, adapter de forge, écriture/publication Git, scheduler concret, submodules/LFS, politique de rétention des snapshots et partage multi-processus de la racine Git.
- engager une prochaine release avec mission explicite ;
- maintenir les domaines futurs non numérotés ;
- reclasser un besoin différé si les preuves obtenues le justifient.
Elle ne doit pas transformer automatiquement PostgreSQL, parsing/index, propositions/admin/auth, forge ou publication en prochaine version uniquement parce que ces domaines sont connus.
Une future mission pourra être engagée depuis la stable `0.0.2` lorsqu'un besoin produit ou d'exploitation choisira explicitement l'un de ces axes. Elle devra repartir de la baseline locale Knowledge et ne consultera PGR que si une réévaluation PGR est elle-même explicitement dans le scope.

100
docs/studies/005-V0_0_2_GIT_SYNC_RECONCILIATION.md Normal file
View File

@@ -0,0 +1,100 @@
<!-- file: docs/studies/005-V0_0_2_GIT_SYNC_RECONCILIATION.md -->
<!-- version: 1 -->
# Réconciliation 0.0.2 — Git générique et synchronisation
## Objet
Cette étude de `0.0.2-beta.1` réconcilie la mission annoncée avec l'implémentation réellement validée par les alphas. Elle n'ajoute aucune fonctionnalité et sert de baseline durable pour la candidate.
## Inventaire matérialisé
Le workspace contient neuf packages :
```text
knowledge-domain-lib famille/source de contenu
knowledge-git-api contrat GitRepository provider-neutral
knowledge-git-lib backend process Git contrôlé
knowledge-sync-api signaux de réconciliation
knowledge-app-lib cas d'usage partagé Changed / Unchanged
knowledge-web-lib runtime Actix/Maud/Vite partagé
knowledge-pgr-server launcher PGR
knowledge-howtos-server launcher HOWTOs
knowledge-snippets-server launcher snippets
```
Aucune crate n'est un placeholder créé uniquement pour refléter un diagramme.
## Chemin Git obtenu
Le chemin de lecture réellement matérialisé est :
```text
GitSourceConfig
-> mirror contrôlé repositories/<source-key>.git
-> remote update --prune
-> rev-parse <reference>^{commit}
-> GitRevision
-> worktree détaché snapshots/<source-key>/<revision>
-> validation HEAD + worktree propre
-> GitSnapshot
```
L'implémentation reste derrière `knowledge-git-api::GitRepository`. Les sources locales utilisent `--no-local`; les opérations sont lancées sans shell, sans prompt interactif et avec hooks neutralisés sur les opérations concernées. Les erreurs publiques n'exposent pas les localisations ou credentials de source.
## Synchronisation obtenue
`knowledge-app-lib` possède le cas d'usage partagé :
```text
RepositorySyncSignal
-> refresh
-> resolve_revision
-> comparer previous_revision
-> Unchanged
ou
-> prepare_snapshot
-> Changed { revision, snapshot }
```
La révision précédente est fournie par l'appelant ; aucune pseudo-base locale n'est ajoutée. `Periodic` utilise le même chemin de réconciliation qu'une cause explicite, sans scheduler concret.
## Autonomie normative
L'adoption PGR `v0.1.3` est fermée comme migration ponctuelle. Les règles, templates et audits nécessaires au travail courant sont possédés par Knowledge. Une session ou version normale repart de la baseline locale et ne recharge pas PGR.
## DEFER confirmés
Restent hors de `0.0.2` :
- adapter Gitea ou autre forge ;
- écriture Git, branches/propositions/rebase/merge/push et publication ;
- PostgreSQL, migrations et persistance durable de dernière révision ;
- moteur de recherche/index applicatif ;
- auth/admin complète et modèle rôles/capabilities ;
- formats finaux HOWTO/snippet et parsing métier ;
- scheduler périodique concret ;
- support explicite submodules/Git LFS ;
- politique de nettoyage/rétention des snapshots ;
- partage concurrent d'une même racine Git entre plusieurs processus ;
- backend secondaire `gix`/`git2` sans nouvelle preuve de besoin.
Ces points ne sont pas des défauts de `0.0.2`; ils nécessitent une mission distincte ou un besoin d'exploitation démontré.
## Réconciliation documentaire
Les anciennes références `alpha.2` à `alpha.5` de la fondation Web sont qualifiées `0.0.1-*` lorsque leur contexte serait ambigu avec les alphas `0.0.2`. La documentation durable distingue désormais clairement :
- fondation/runtime Web stable `0.0.1` ;
- backend Git et synchronisation `0.0.2` ;
- adoption PGR `v0.1.3` comme provenance historique, non comme dépendance courante.
## Revue d'horizon
La revue ne réserve aucune release après `0.0.2`. Plusieurs domaines futurs sont connus, mais aucun n'a encore un scope et un ordre suffisamment décidés pour devenir la prochaine mission autoritaire.
La prochaine version sera engagée uniquement lorsqu'un besoin produit ou d'exploitation choisira explicitement un axe. Aucun prompt `0.0.3` n'est créé en `beta.1`.
## Conclusion
Le scope fonctionnel de `0.0.2` est complet et cohérent avec sa mission. `beta.1` peut préparer la release candidate sans ajouter de fonctionnalité ; la RC devra se concentrer sur l'intégrité des artefacts, la reproductibilité Git, la gate Rust complète et la non-régression Web/runtime.

27
docs/validation/001-VALIDATION_MATRIX.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 27 -->
<!-- version: 28 -->
# Matrice de validation Knowledge
@@ -734,3 +734,28 @@ La tranche de cas d'usage de synchronisation doit prouver :
- `git diff --cached --check` propre avant commit.
Le `PASS` d'`alpha.5` ferme le scope fonctionnel alpha de `0.0.2` et autorise uniquement la préparation de `beta.1` de réconciliation et revue d'horizon.
## Gate de `0.0.2-beta.1`
La réconciliation beta doit prouver :
- `VERSION = 0.0.2-beta.1` et version workspace identique ;
- history `history/0.0.2/alpha.5.md` présent avec statut `PASS` et committé avant application ;
- aucun nouveau package Cargo, package npm, contrat runtime ou comportement Git introduit ;
- workspace Cargo composé exactement de neuf packages ;
- étude `005-V0_0_2_GIT_SYNC_RECONCILIATION.md` présente et cohérente avec l'implémentation ;
- `knowledge-git-lib` documentée comme backend Git générique réel et `knowledge-app-lib` comme owner du cas d'usage partagé ;
- références historiques aux alphas Web de fondation qualifiées `0.0.1-*` lorsqu'elles seraient ambiguës ;
- `DEFER` PostgreSQL/forge/auth/admin/formats finaux/écriture Git/scheduler/submodules-LFS/rétention snapshots/multi-processus conservés ;
- revue d'horizon réalisée sans engager ni numéroter de release après `0.0.2` ;
- `CHANGELOG.md` contient une section `0.0.2 (candidate)` utile et sans catalogue de fixes internes ;
- `cargo fmt --all` puis `cargo fmt --all -- --check` exécutés avant tout audit Rust ;
- audits Markdown et Rust locaux propres ;
- `cargo metadata`, `cargo check --workspace`, Clippy strict et tests workspace propres ;
- baseline Web `npm ci`, `npm run typecheck` et `npm run build` propre ;
- manifest Vite généré parsable avec l'entrée stable `src/main.ts` ;
- aucun diff sous `crates/` ou `Web/` ;
- `Cargo.lock` présent localement, ignoré et non suivi ;
- hygiène texte et `git diff --cached --check` propres.
Un `PASS` de `beta.1` autorise uniquement `0.0.2-rc.1`. Aucun prompt de release suivante n'est créé tant que la revue d'horizon ne l'a pas engagée.