sasedev-knowledge/deltas/0.0.3/alpha.2.md

Delta 0.0.3-alpha.2 — contrat d'écriture Git provider-neutral

Baseline requise

Partir de 0.0.3-alpha.1.fix.2 après application, commit et push de son history PASS.

La version devient :

0.0.3-alpha.2

Objet

Matérialiser uniquement la frontière publique provider-neutral nécessaire aux futures opérations d'écriture Git, sans implémenter encore le worktree d'écriture ou le push distant réel.

La tranche :

• conserve GitRepository comme contrat de lecture inchangé ;
• ajoute GitRepositoryWriter comme capacité distincte afin de ne pas imposer l'écriture aux consommateurs/fakes lecture seule ;
• introduit GitMutationPath pour des chemins relatifs normalisés, sans . / .., séparateur plateforme, chemin absolu, drive Windows ou composant .git ;
• introduit GitFileMutation pour écrire/créer/remplacer ou supprimer un fichier ;
• introduit GitCommitIdentity et exige une identité explicite ;
• introduit GitBranch et borne la publication à une référence complète valide sous refs/heads/... ;
• introduit GitRemoteState pour représenter explicitement branche absente ou révision attendue ;
• introduit GitWriteRequest, GitPushRequest et GitPushOutcome pour séparer création de candidate, mise à jour distante gardée et conflit ;
• rejette une requête sans mutation, un message vide/NUL et plusieurs mutations visant le même chemin ;
• documente la matérialisation de la frontière sans déplacer les responsabilités backend prévues pour alpha.3 / alpha.4.

Aucun processus Git d'écriture n'est lancé par cette tranche.

Scope des fichiers

REPLACE :

VERSION
Cargo.toml
README.md
crates/knowledge-git-api/src/lib.rs
crates/knowledge-git-api/unit_tests/lib.rs
docs/architecture/002-KNOWLEDGE_ARCHITECTURE.md
docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md
docs/validation/001-VALIDATION_MATRIX.md

ADD :

crates/knowledge-git-api/src/write.rs
deltas/0.0.3/alpha.2.md

DELETE : aucun.

Aucun fichier sous knowledge-git-lib, knowledge-app-lib ou Web/ n'est modifié.

Aucun history alpha.2 n'est inclus dans ce delta.

Contrat public matérialisé

Le contrat expose les valeurs suivantes depuis la façade knowledge_git_api :

GitWriteInputError
GitMutationPath
GitFileMutation
GitCommitIdentity
GitBranch
GitRemoteState
GitWriteRequest
GitPushRequest
GitPushOutcome
GitRepositoryWriter

Le chemin conceptuel reste :

GitRevision de base
+ mutations confinées
+ identité/message explicites
-> create_candidate
-> GitRevision candidate

GitBranch
+ GitRemoteState attendu
+ GitRevision candidate
-> push_candidate
-> Updated ou Conflict

alpha.2 définit ce contrat mais ne prétend pas encore prouver le confinement filesystem face aux symlinks, la neutralisation des hooks, la création effective d'un commit ou le compare-and-exchange distant. Ces preuves appartiennent au backend knowledge-git-lib des tranches suivantes.

Gate opérateur

Exécuter depuis la racine du dépôt après application du delta :

test "$(cat VERSION)" = '0.0.3-alpha.2'
grep -F 'version = "0.0.3-alpha.2"' Cargo.toml

git diff --check

python3 -B scripts/audit_markdown_headers.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts deltas history
python3 -B scripts/audit_markdown_links.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts deltas history
python3 -B scripts/audit_markdown_tables.py README.md RULES.md ROADMAP.md CHANGELOG.md docs prompts deltas history

cargo fmt --all
cargo fmt --all -- --check

python3 -B scripts/audit_rust_test_layout.py crates
python3 -B scripts/audit_rust_blank_lines.py crates
python3 -B scripts/audit_rust_item_spacing.py crates
python3 -B scripts/audit_rust_module_order.py crates
python3 -B scripts/audit_rust_trait_import_blocks.py crates
python3 -B scripts/audit_rust_reexport_blocks.py crates
python3 -B scripts/audit_rust_crate_root_facades.py crates
python3 -B scripts/audit_rust_export_completeness.py --root . --summary-only

cargo metadata --format-version 1 --no-deps > /tmp/sasedev-knowledge-0.0.3-alpha.2-metadata.json
cargo check --workspace
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test -p knowledge-git-api --all-targets --all-features
cargo test --workspace --all-targets --all-features

python3 - <<'PYGATE'
from pathlib import Path

api = Path('crates/knowledge-git-api/src/lib.rs').read_text(encoding='utf-8')
write = Path('crates/knowledge-git-api/src/write.rs').read_text(encoding='utf-8')
read_contract = Path('crates/knowledge-git-api/src/repository.rs').read_text(encoding='utf-8')
manifest = Path('crates/knowledge-git-api/Cargo.toml').read_text(encoding='utf-8')
plan = Path('docs/plans/003-V0_0_3_GIT_WRITE_PLAN.md').read_text(encoding='utf-8')
changelog = Path('CHANGELOG.md').read_text(encoding='utf-8')

for item in (
    'GitWriteInputError',
    'GitMutationPath',
    'GitFileMutation',
    'GitCommitIdentity',
    'GitBranch',
    'GitRemoteState',
    'GitWriteRequest',
    'GitPushRequest',
    'GitPushOutcome',
    'GitRepositoryWriter',
):
    assert item in api, item
    assert item in write, item

assert 'fn refresh(' in read_contract
assert 'fn resolve_revision(' in read_contract
assert 'fn prepare_snapshot(' in read_contract
assert 'create_candidate' not in read_contract
assert 'push_candidate' not in read_contract

assert 'refs/heads/' in write
assert 'ProtectedGitPath' in write
assert 'DuplicateMutationPath' in write
assert 'GitRemoteState::Absent' not in write or 'GitRemoteState' in write
assert 'rebase' not in write.lower()
assert 'merge' not in write.lower()

for forbidden in ('actix', 'tokio', 'gitea', 'gitlab', 'github', 'postgres', 'sqlx', 'diesel'):
    assert forbidden not in manifest.lower(), forbidden

assert '`alpha.1.fix.2` a complété la gate documentaire et technique en `PASS`' in plan
assert '### alpha.2 — contrat d\'écriture provider-neutral' in plan
assert '## 0.0.3' not in changelog

assert Path('history/0.0.3/alpha.1.fix.2.md').is_file()
assert not Path('history/0.0.3/alpha.2.md').exists()
assert not Path('crates/knowledge-forge-gitea-lib').exists()
assert not Path('crates/knowledge-store-postgres-lib').exists()
assert not Path('migrations').exists()

print('Knowledge 0.0.3-alpha.2 write-contract audit: clean')
PYGATE

python3 - <<'PYTEXT'
from pathlib import Path

roots = [Path('README.md'), Path('RULES.md'), Path('ROADMAP.md'), Path('CHANGELOG.md'), Path('docs'), Path('prompts'), Path('deltas'), Path('history')]
paths = []
for root in roots:
    if root.is_file():
        paths.append(root)
    elif root.is_dir():
        paths.extend(path for path in root.rglob('*') if path.is_file())
for path in paths:
    data = path.read_bytes()
    assert b'\r' not in data, path
    assert data.endswith(b'\n'), path
    assert not data.endswith(b'\n\n'), path
    text = data.decode('utf-8')
    for number, line in enumerate(text.splitlines(), start=1):
        assert line == line.rstrip(' \t'), (path, number)
print(f'Knowledge 0.0.3-alpha.2 text hygiene: clean ({len(paths)} file(s))')
PYTEXT

test -z "$(git diff --name-only -- crates/knowledge-git-lib crates/knowledge-app-lib Web)"
test ! -e history/0.0.3/alpha.2.md

test -f Cargo.lock
git check-ignore -q Cargo.lock
if git ls-files --error-unmatch Cargo.lock >/dev/null 2>&1; then
    echo 'Cargo.lock must remain untracked for Knowledge' >&2
    exit 1
fi

test -f Web/knowledge-template-lab/package-lock.json

git add -A
git diff --cached --check
git status --short

La gate ne rejoue pas npm/Vite/HTTP : Web/, les launchers et leur contrat runtime ne sont pas modifiés.

Transition

PASS

Produire history/0.0.3/alpha.2.md, l'appliquer, commit/push 0.0.3-alpha.2, puis préparer 0.0.3-alpha.3 pour le worktree d'écriture isolé et le commit candidat réel dans knowledge-git-lib.

FAIL / PARTIAL / BLOCKED

Conserver le résultat réel dans son history avant toute correction. Une correction bornée utilise alpha.2.fix.N ; une modification de la mission ou de la frontière d'ownership exige un REPLAN explicite plutôt qu'un fix absorbant une nouvelle fonctionnalité.