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

0.0.4-alpha.1

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-10-01 10:49:09 +02:00
parent b382397244
commit b55eb23dc0
12 changed files with 961 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,20 +1,22 @@
<!-- file: docs/architecture/001-PROJECT_PROFILE.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# Profil du projet Knowledge
## Baseline autoritaire
La stable produit depuis laquelle `0.0.3` est ouverte est :
La stable produit depuis laquelle `0.0.4` est ouverte est :
```text
Knowledge stable tag v0.0.2
Knowledge stable commit 183d354a67bec6d2d512c4898f5189759a6120b0
Knowledge archive SHA-256 0e518c7eaad115811cccc8fb2b38a1e68150ec985c2ca72ec08a9ca5bbb202ce
Knowledge publish report sasedev-knowledge-0.0.2-publish.001-report.md = PASS
Knowledge start prompt prompts/003-V0_0_3_START_PROMPT.md
Knowledge stable tag v0.0.3
Knowledge stable commit b3823972449150b72905930b806d4d15471cddce
Knowledge archive SHA-256 82407dc2a83be878daa65692f975681428d0adc721ff249c3c9020e3a9d1f29d
Knowledge publish report sasedev-knowledge-0.0.3-publish.001-report.md = PASS
Knowledge start prompt prompts/004-V0_0_4_START_PROMPT.md
```
L'archive taggée `v0.0.3` a été vérifiée avant le cadrage `0.0.4-alpha.1` : `VERSION` et le workspace Cargo valent `0.0.3`, les douze deltas et douze histories `0.0.3` sont appariés, `rel.1.fix.1 = PASS` clôt la release et le commentaire ZIP contient le commit stable ci-dessus.
La fondation `0.0.1` a été construite sous PGR `v0.1.1`. Cette identité reste historique dans les artefacts `0.0.1`.
Le démarrage explicite de `0.0.2` a réévalué PGR et a retenu la stable suivante comme source d'adoption :
@@ -91,7 +93,7 @@ Le détail de la migration depuis les owners PGR `v0.1.3`, y compris les décisi
| 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é |
| PostgreSQL | `KEEP-LOCAL` | une base logique partagée ; `0.0.4` matérialise sa première fondation sans déplacer la vérité éditoriale de Git |
| Rust stable / édition 2024 | `ADOPT` | owner local `docs/rules/510-RUST_CARGO.md` |
| Workspace Cargo | `ADOPT` | configuration locale + owner `510-RUST_CARGO.md` |
| `Cargo.lock` | `KEEP-LOCAL` | généré localement et ignoré ; manifests Cargo versionnés |
@@ -105,8 +107,8 @@ Le détail de la migration depuis les owners PGR `v0.1.3`, y compris les décisi
| 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 |
| Toolkit PostgreSQL | `KEEP-LOCAL` | `tokio-postgres` + `deadpool-postgres`, async/Tokio et SQL explicite ; aucun ORM sélectionné |
| Migrations PostgreSQL | `KEEP-LOCAL` | SQL versionné possédé par `knowledge-store-postgres-lib`, appliqué explicitement via Refinery |
| 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 |
@@ -133,12 +135,17 @@ knowledge-snippets-server launcher snippets mince
`knowledge-git-lib` devient réelle en `0.0.2-alpha.2` puis implémente le chemin de lecture Git dans `alpha.3`. `knowledge-app-lib` devient réelle en `0.0.2-alpha.5` : l'orchestration refresh / résolution / comparaison / snapshot confirme une responsabilité application partagée distincte du backend Git et des launchers.
`0.0.4-alpha.1` retient comme prochaine responsabilité réelle, sans encore la matérialiser dans cette tranche :
```text
knowledge-store-postgres-lib pool, migrations et état applicatif PostgreSQL partagé
```
Les responsabilités suivantes restent candidates et non matérialisées :
```text
knowledge-store-postgres-lib état applicatif PostgreSQL partagé
knowledge-forge-gitea-lib adapter Gitea optionnel
knowledge-logging-lib diagnostics partagés, seulement sur besoin multi-runtime réel
knowledge-forge-gitea-lib adapter Gitea optionnel
knowledge-logging-lib diagnostics partagés, seulement sur besoin multi-runtime réel
```
Règles de création :
@@ -177,3 +184,25 @@ Restent différés après `0.0.2` : adapter Gitea, PostgreSQL/migrations, moteur
La revue d'horizon `0.0.2-beta.1` n'avait réservé aucune release suivante. L'ouverture explicite de `0.0.3` a consommé uniquement le `DEFER` d'écriture Git contrôlée : worktree d'écriture isolé, commit candidat et push de branche gardé. Rebase/merge automatique et workflow complet de proposition restent différés.
La revue `0.0.3-beta.1` sélectionne désormais la fondation PostgreSQL partagée comme prochaine mission `0.0.4`, sans préchoisir son driver/ORM avant l'étude de démarrage. Elle réordonne ensuite l'horizon produit pour rendre visibles les phases de modèles/projections, templates publics, templates admin, intégration Actix/Maud puis workflow de gestion/publication. Gitea, scheduler, recherche avancée, quatrième application admin et partage multi-processus restent différés tant que leurs déclencheurs ne sont pas matérialisés.
## Ouverture `0.0.4` — fondation PostgreSQL partagée
Après publication vérifiée de `v0.0.3`, `0.0.4-alpha.1` consomme les `DEFER` portant sur le toolkit PostgreSQL et les migrations.
La décision locale est :
```text
owner prévu knowledge-store-postgres-lib
driver tokio-postgres 0.7
modèle SQL explicite, sans ORM
pool deadpool-postgres 0.14
migrations SQL versionné + Refinery 0.9
premier état source logique + dernière révision synchronisée
autorité contenu Git
```
Aucune crate n'est créée pendant `alpha.1`. La tranche établit seulement l'étude et le plan qui autoriseront `alpha.2` après gate opérateur `PASS`.
La configuration physique Git reste possédée par `knowledge-git-lib`. Le premier schéma PostgreSQL ne stocke pas de credentials Git et ne transforme pas les URLs/paths physiques en vérité métier. La configuration de connexion PostgreSQL est injectée par la composition, non lue implicitement par la future crate de stockage.
Les `DEFER` Gitea/forge, scheduler, recherche avancée, auth/capabilities, formats finaux de contenu, quatrième application admin, partage multi-processus de racine Git, LFS/submodules et rétention avancée restent inchangés. L'horizon `0.0.5` à `0.0.10` reste cohérent et n'est pas replanifié par cette étude.

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

@@ -1,5 +1,5 @@
<!-- file: docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md -->
<!-- version: 18 -->
<!-- version: 19 -->
# Architecture de fondation Knowledge
@@ -36,6 +36,8 @@ 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.
`0.0.4-alpha.1` retient `knowledge-store-postgres-lib` comme prochain owner concret du pool, des migrations et de l'état PostgreSQL partagé. Cette crate n'est pas encore créée dans la tranche de cadrage et aucun `knowledge-store-api` symétrique n'est introduit sans besoin de substitution démontré.
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.
Le workspace est une application déployable à train de release unique. Knowledge choisit néanmoins de conserver `Cargo.lock` comme état généré local et ignoré par Git ; les manifests Cargo portent le contrat versionné des dépendances. Les artefacts Cargo sont dirigés hors du dépôt vers `../builds/sasedev-knowledge/target/`.
@@ -300,7 +302,30 @@ La baseline retient **une base PostgreSQL logique partagée** par les trois appl
Ce choix est justifié par l'état transversal : identités, sessions, propositions, synchronisation, relations entre familles, index et recherche. Il évite trois bases divergentes pour des concepts qui appartiennent à la même plateforme.
PostgreSQL MAY contenir des documents/index/métadonnées dérivés et assurer une première capacité de recherche. Aucun moteur de recherche externe n'est sélectionné en `0.0.1`.
### Fondation sélectionnée pour `0.0.4`
`0.0.4-alpha.1` sélectionne `tokio-postgres` comme driver PostgreSQL async natif, `deadpool-postgres` comme pool et Refinery comme mécanisme de migrations. La future crate `knowledge-store-postgres-lib` possédera la composition de ces trois responsabilités, la conversion de leurs erreurs en erreurs publiques récupérables et les opérations PostgreSQL concrètes. Knowledge ne sélectionne pas d'ORM, ne recherche pas d'abstraction multi-SGBD et n'introduit pas de `knowledge-store-api` tant qu'une seconde implémentation de stockage ou une frontière passive réellement indépendante n'est pas démontrée.
La configuration est injectée par la composition : la crate de stockage reçoit une URL/options de connexion et des paramètres de pool. Elle ne lit pas directement les variables d'environnement du processus et ne journalise jamais l'URL ou les credentials. Une connexion ou migration impossible retourne une erreur ; aucun fallback fichier/mémoire ne masque l'indisponibilité PostgreSQL.
Le premier schéma utile est volontairement borné :
```text
knowledge_sources
source_id TEXT PRIMARY KEY
family TEXT NOT NULL
git_reference TEXT NOT NULL
knowledge_source_sync_state
source_id TEXT PRIMARY KEY REFERENCES knowledge_sources(source_id)
last_synchronized_revision TEXT NOT NULL
```
`family` reste aligné sur `ContentFamily` et sera contraint aux valeurs supportées par le domaine. `git_reference` est la référence Git logique à suivre ; la localisation physique locale/remote et les credentials restent hors de cette table et sous les frontières de configuration appropriées. La dernière révision synchronisée est un état applicatif, pas une nouvelle autorité de contenu : elle peut être reconstruite/réconciliée à partir de Git et une valeur obsolète provoque au pire une resynchronisation.
Les migrations sont des fichiers SQL versionnés placés sous l'owner de stockage et appliqués explicitement par Refinery. La stratégie de test utilise une URL PostgreSQL de test fournie explicitement et un schéma unique éphémère par exécution ; la gate doit être `BLOCKED` si le service PostgreSQL requis n'est pas disponible, jamais convertir cette absence en test artificiellement passé. Le même mécanisme peut cibler un PostgreSQL local ou un service PostgreSQL éphémère de CI sans rendre Docker obligatoire pour la bibliothèque.
PostgreSQL MAY contenir ultérieurement des documents/index/métadonnées dérivés et assurer une première capacité de recherche. Le corps publié et ses métadonnées éditoriales autoritaires restent dans Git. `0.0.4` ne matérialise pas encore le parsing/projection final prévu par l'horizon `0.0.5`.
Les enregistrements dérivés doivent porter au minimum l'identité de famille/source et la révision Git afin de savoir exactement quel contenu ils représentent.
@@ -399,6 +424,23 @@ Le push distant gardé reste réservé à `alpha.4`. `alpha.3` ne met à jour au
PostgreSQL, workflow complet de proposition, auth/admin, parsing final et adapter Gitea restent des missions distinctes.
## Ouverture `0.0.4` — persistance partagée
La stable `v0.0.3` ayant fermé le chemin Git générique, `0.0.4` matérialise la première persistance partagée nécessaire aux prochains cas d'usage sans déplacer l'autorité éditoriale.
La trajectoire retenue est :
```text
alpha.1 étude, ownership, schéma, migrations et tests
alpha.2 crate PostgreSQL + pool + première migration
alpha.3 persistance source logique + état de synchronisation
alpha.4 raccord applicatif de la révision précédente persistée
beta réconciliation + horizon
rc/rel stabilisation et publication
```
Le raccord applicatif futur doit conserver la primitive `synchronize_repository` provider-neutral : la persistance fournit la révision précédente et reçoit la révision observée, mais ne devient ni un backend Git ni une condition pour interpréter l'identité du commit.
## 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é.