Procédures communes des lots 1 à 4 (P-GIT, P-API, P-COLLECTEUR, P-N8N)

Rédigé le 2026-11-18 à partir du lot 4 §5, des relectures (review/lot1-review.md, review/lot4-review.md, review/cross-lot-review.md) et des arbitrages review/01-arbitrages.md (G2, G3). Les quatre noms P-GIT, P-API, P-COLLECTEUR, P-N8N sont stables : chaque lot y renvoie et ne garde que ses vérifications propres.

Conventions : Lisbonne = UTC en novembre. EE = CMC-event-engine, AU = CMC-automations. Serveur Pro = root@<serveur Event Engine>. Toute commande sur le serveur qui lance Python est préfixée par timeout ; les scripts copiés dans /tmp sont supprimés à la fin (ps aux | grep '/tmp/' | grep -v grep, CLAUDE.md #10, #11).

0. Règles transverses

  1. Trois portes Git séparées (G3) : « go commit », puis « go push », puis « go déploiement » (un par livraison). Un « go commit » peut couvrir une série de commits locaux annoncée avec sa liste. Aucun commit sans attribution IA (#5b).
  2. Context7 obligatoire avant de modifier du code qui touche httpx, Playwright ou n8n (nœuds, expressions, API REST) : citer la page lue dans le compte rendu.
  3. Au plus une livraison de production par jour, et au plus une intervention par jour sur la voie X (Core, Process One Source, Process Source Queue, Enrich, Normalize, X REST, Add Tweet Manually, collecteur X, X Stream Health).
  4. Pas de livraison par-dessus une autre session : journal du jour, git log et versions live relus juste avant (P-GIT étape 1).
  5. Toute livraison de l'API passe par P-API avec drain (incident SI145759 du 10/11, docs/archive/event-engine-pipeline-history.md:15 : un redémarrage pendant Normalize/Enrich bloque la source en x_context_execution_failed).
  6. État de départ commun (relecture transversale, constat 9), à remesurer une fois avant le premier lot, puis après chaque livraison : suite backend DATABASE_URL="sqlite://" env -u OPENROUTER_API_KEY <venv>/bin/python -m pytest -q (6 échecs attendus au 18/11) ; ruff check src tests --no-cache comparé à l'état de départ (171 erreurs au 18/11), jamais utilisé comme critère absolu ; automations python -m pytest -q tooling/n8n/tests workflows (1 échec connu, retiré par le lot 4a ; 0 attendu ensuite) et node --test sur les fichiers *.test.js|*.test.mjs (commande de la CI AU/.github/workflows/test.yml).

Fenêtres canoniques (UTC, novembre) — les seules valables pour les lots 1 à 4

Appelants de l'API relevés dans les exports live du 18/11 (recherche de event-engine-api:3282 dans live/*.json, puis accessibilité depuis chaque déclencheur) :

Appelant de l'API Horaires (Lisbonne = UTC) Durée à prévoir
Process Source Queue → Process One Source, Normalize, Enrich, Core, X REST toutes les 10 s jusqu'à 30 min par source
Blog Collector : lecture / réclamation → Process One Source 00:05, 06:05, 12:05, 18:05 / chaque minute lecture jusqu'à 60 min
Conference Collector 01:20 jusqu'à ~4 h (12 rondes), 6 h au plus
Unlock Collector 02:40 jusqu'à ~5 h (16 rondes)
Audit Social Sources (via X REST) ; Reconcile X Stream Sources (appelle l'Audit) 03:20 ; 05:02 —
CoinGecko Maintain (via X REST) 04:30 —
Editorial X Publisher (Render Editorial PNG → /render-editorial-x-image, WZBAd86SLDfK3ZXh, fuseau Europe/Lisbon) 14:00, 15:00, 16:00, 18:00, jeudi 20:00 ; Schedule Watchlist Retry */5 (les 7 déclencheurs peuvent atteindre ce nœud) —
Editorial X Metrics (via X REST) chaque heure à :25 —
X REST Context Health :00 et :30 —
Repair Missing Embeddings */5 —
Add Tweet Manually (manuel, Telegram) à la demande —

Fenêtres qui évitent tous ces horaires :

1. P-GIT

Étape 1 — Coordination (avant de commencer, puis avant chaque push et chaque déploiement).

Étape 2 — Worktree. git -C <repo> worktree add --detach wip/worktrees/<lot>-<repo> origin/main (#52). Notes et preuves dans wip/<lot>/ ; copier ce qui doit survivre avant git worktree remove.

Étape 3 — Commits (« go commit »). Présenter à Anthony la liste des commits (titre, git diff --stat, tests passés, passe simplify faite) ; un commit de « checkpoint » après déploiement n8n (positions et version live, P-N8N étape 11) est annoncé dans la liste comme commit prévu, et son diff est montré avant d'être commité.

Étape 4 — Push (« go push »). git fetch origin ; si origin/main a bougé, rebaser nos commits seulement, relancer les tests, puis git push origin HEAD:main (avance rapide). Noter le SHA épinglé S.

Étape 5 — Contrôle de ce que la livraison emporte (avant « go déploiement »).

Étape 6 — Après. Entrée datée en tête de docs/EVENT_ENGINE_PIPELINE.md (SHA, versions, tag de rollback, preuves wip/<lot>/), retrait des worktrees, nettoyage /tmp sur Hostinger.

2. P-API (livraison de event-engine-api)

Étape 0 — Préalables. P-GIT 1-5 faits ; Context7 si httpx/Playwright/n8n touchés ; fenêtre §0 ; « go déploiement ».

Étape 1 — Lectures sur le serveur (bloquantes).

ssh root@&lt;serveur Event Engine&gt; 'cd /root/CMC-event-engine && git rev-parse --short HEAD && git status --short | head -3 \
  && docker inspect event-engine-api --format "{{.Image}} {{.State.StartedAt}}" \
  && (pgrep -af "compose (build|up)" || true) && docker compose images event-engine-api'
ssh root@&lt;serveur Event Engine&gt; 'docker run --rm --entrypoint pip "$(docker inspect --format "{{.Image}}" event-engine-api)" freeze' > wip/<lot>/pip-freeze-before.txt
ssh root@&lt;serveur Event Engine&gt; 'docker exec event-engine-api sh -c "env | cut -d= -f1 | grep -iE \"proxy|ssl_cert\" || true"'

Attendu : HEAD = D, arbre propre, conteneur démarré depuis plus de 30 min, aucun build en cours, aucune variable proxy ou certificat inattendue. Noter le nom réel de l'image du service (compose n'a pas de clé image: ; le nom vient du projet, EE/docker-compose.yml:2-4).

Étape 2 — Build et contrôles, sans toucher à la file (09:15-10:05).

cd /root/CMC-event-engine
docker tag "$(docker inspect --format '{{.Image}}' event-engine-api)" cmc-event-engine-api:rollback-pre-<lot>-<AAAAMMJJ>
git fetch origin main && git checkout --detach <S>
docker compose build --progress=plain event-engine-api 2>&1 | tee /root/build-<lot>-<AAAAMMJJ>.log   # jamais --pull ni --no-cache
NEW=<image construite, lue par docker compose images event-engine-api>
docker run --rm --entrypoint pip "$NEW" freeze > /root/pip-freeze-after-<lot>.txt
for img in "$(docker inspect --format '{{.Image}}' event-engine-api)" "$NEW"; do
  docker run --rm --entrypoint sh "$img" -c 'ffmpeg -version | head -1; python -m playwright --version; ls /ms-playwright'; done

Le conteneur en service n'est pas touché par le build.

Critère d'arrêt (dépendances non figées), avant tout drain. pyproject.toml n'a que des bornes >= (EE/pyproject.toml:6-23) et le Dockerfile installe le système (apt-get install ffmpeg), puis Python (pip install), puis Chromium (playwright install --with-deps), avant COPY src/ src/ (EE/Dockerfile). Règle :

Étape 3 — Drain autour du seul redémarrage (10:06-10:08), réactivation garantie. Le drain n'enveloppe que docker compose up -d et l'attente de /health :

# commande passée au drain (une seule commande ssh)
ssh root@&lt;serveur Event Engine&gt; 'cd /root/CMC-event-engine && date -u +%T && docker compose up -d --no-deps event-engine-api \
  && until curl -fsS http://127.0.0.1:3282/health >/dev/null; do sleep 1; done && date -u +%T \
  && docker exec root-n8n-1 wget -qO- http://event-engine-api:3282/health'

Étape 4 — Signal positif après la réactivation : dans les 10 min, des attempts démarrent quand des éléments X sont éligibles (requête S1).

Étape 5 — Vérifications après, en lecture seule (voie touchée + voie X).

Étape 6 — Rollback et validité de l'image.

2.1 Gabarit drain_api.py (à écrire dans wip/<lot>/, avant le lot 4a)

"""Drain the X lane around one `docker compose up -d`, always reactivate. Start at 09:56 UTC.
Usage: drain_api.py [--keep-blog] [--not-before 10:06] [--restart-by 10:08] -- <command...>"""
import datetime as dt, http.cookiejar, json, os, subprocess, sys, time, urllib.parse, urllib.request
B = "https://&lt;instance n8n Pro&gt;"
QUEUE, PROCESSOR, NORMALIZE, ENRICH, CORE, BLOG = ("o4cmp66lDjKDOF4v", "awrB2Ymt3iZPp14k", "9pA9xizup7Zcq846",
                                                   "nBnnkylOa2NRUegp", "1nswAXAfsck9e9uC", "mYAuzz1BuvjiJtEF")
op = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(http.cookiejar.CookieJar()))
def call(method, path, body=None):
    r = urllib.request.Request(B + path, data=None if body is None else json.dumps(body).encode(), method=method,
                               headers={"Content-Type": "application/json", "Accept": "application/json"})
    with op.open(r, timeout=120) as resp:
        v = json.load(resp); return v.get("data", v)
call("POST", "/rest/login", {"emailOrLdapLoginId": os.environ.get("N8N_PRO_EMAIL", "&lt;e-mail de connexion n8n&gt;"), "password": os.environ["N8N_PRO_PASSWORD"]})  # n8n-pro.env ne contient que N8N_PRO_PASSWORD (vérifié 18/11)
def running(wid):
    q = urllib.parse.urlencode({"limit": 50, "filter": json.dumps({"workflowId": wid, "status": ["running"]})})
    return [r["id"] for r in call("GET", "/rest/executions?" + q).get("results", []) if r.get("stoppedAt") is None]
targets = [QUEUE] + ([] if "--keep-blog" in sys.argv else [BLOG])
saved = {w: call("GET", f"/rest/workflows/{w}") for w in targets}
assert all(d["active"] and d["versionId"] == d["activeVersionId"] for d in saved.values()), "unaligned before drain"
command = sys.argv[sys.argv.index("--") + 1:]
def today_at(flag, default):
    hh, mm = (sys.argv[sys.argv.index(flag) + 1] if flag in sys.argv else default).split(":")
    return dt.datetime.now(dt.UTC).replace(hour=int(hh), minute=int(mm), second=0, microsecond=0)
not_before, restart_by = today_at("--not-before", "10:06"), today_at("--restart-by", "10:08")
try:
    for w in targets: call("POST", f"/rest/workflows/{w}/deactivate", {})
    while any(running(w) for w in (PROCESSOR, NORMALIZE, ENRICH, CORE)) or dt.datetime.now(dt.UTC) < not_before:
        if dt.datetime.now(dt.UTC) >= restart_by:
            raise TimeoutError("X lane not drained by the restart limit: restart aborted for today")
        time.sleep(5)
    subprocess.run(command, check=True, timeout=180)
finally:
    for w, d in saved.items():
        call("POST", f"/rest/workflows/{w}/activate", {"versionId": d["activeVersionId"]})
        back = call("GET", f"/rest/workflows/{w}")
        print(w, back["active"], back["versionId"] == back["activeVersionId"] == d["activeVersionId"])

Lancer avec set -a; . ~/.local/state/coinmarketcal/n8n-pro.env; set +a dans la même commande ; le mot de passe n'apparaît ni en argument ni dans le fichier. Si le filtre status n'est pas accepté par n8n 2.47.3 (à vérifier une fois en lecture seule), filtrer côté client sur stoppedAt is None en paginant par cursor (limit=50, memory/feedback_n8n.md:430).

3. P-COLLECTEUR (x-stream-collector, checkout /root/CMC-event-engine-x-stream)

Reprend la procédure vérifiée de plan/lot1.md §5.3 et review/lot1-review.md (constats 8 et suivants), et docs/TOOLS.md:125-140.

Étape 0. P-GIT 1-5 ; « go déploiement » séparé de celui de l'API ; fenêtre 21:00-22:00, au moins 24 h après une livraison de l'API, pas le jour d'une autre intervention sur la voie X.

Étape 1 — Ce que la livraison emporte, recalculé le jour même (bloquant).

cd /root/CMC-event-engine-x-stream && git rev-parse --short HEAD && git status --short | head -3   # HEAD = commit documenté, arbre propre
git fetch origin main
git log --oneline <HEAD>..<S> -- src/x_stream src/config.py src/db.py src/models/__init__.py src/models/source_inbox.py \
  src/__init__.py src/services/__init__.py src/services/source_renderer/__init__.py src/services/source_renderer/network.py \
  Dockerfile pyproject.toml docker-compose.yml docker
# après le lot 2, ajouter : src/services/web/__init__.py src/services/web/network.py

Liste de chemins identique à plan/lot1.md §5.3. Le résultat doit être égal à la liste relue par le lot ; sinon arrêt. La fermeture des imports de python -m src.x_stream est à recalculer si un lot l'a élargie (après le lot 1 livraison B : src.services.source_renderer.network, puis src.services.web.network après le lot 2).

Étape 2 — Contrôles. curl -fsS http://127.0.0.1:3284/health (healthy: true) ; docker exec x-stream-collector sh -c 'env | cut -d= -f1 | grep -iE "proxy|ssl_cert" || true' vide ; docker compose config --services ; docker compose version puis docker compose up --dry-run -d --no-deps x-stream-collector (détecte un « Pool overlaps » sur ipv6-egress) ; docker run --rm --entrypoint pip <image actuelle> freeze gardé.

Étape 3 — Build et redémarrage.

docker tag "$(docker inspect --format '{{.Image}}' x-stream-collector)" cmc-x-stream-collector:rollback-pre-<lot>-<AAAAMMJJ>
git checkout --detach <S>
docker compose build --progress=plain x-stream-collector 2>&1 | tee /root/build-collector-<lot>-<AAAAMMJJ>.log
docker run --rm --entrypoint pip <image construite> freeze   # même critère d'arrêt que P-API étape 2 (couches avant `COPY src` CACHED, sinon pip, ffmpeg et Chromium comparés)
docker compose up -d --no-deps x-stream-collector
curl -fsS http://127.0.0.1:3284/health && docker exec root-n8n-1 wget -qO- http://x-stream-collector:3284/health

Ne lancer que ces deux commandes depuis ce dossier (son compose décrit aussi l'API et la sandbox : une commande globale créerait des doublons).

Étape 4 — Vérifications (15 min). healthy, rules_in_sync, required_recovery_pending=false, tweetapi_last_success_at récent ; RestartCount inchangé ; docker ps et docker network ls sans nouvel élément ; nouveaux Source Items X conformes aux attentes du lot ; X Stream Health sans alerte.

Étape 5 — Rollback. docker tag cmc-x-stream-collector:rollback-pre-<lot>-<AAAAMMJJ> <image du projet collecteur, docker compose images> && docker compose up -d --no-deps --no-build x-stream-collector, puis git checkout --detach <HEAD d'avant>. Tant qu'un commit utile au collecteur est déployé sur l'API mais pas sur le collecteur, l'écrire dans le journal : « poussé, pas encore déployé (collecteur) ».

4. P-N8N (Definition of Done #61, dans cet ordre)

Pour un workflow W, candidat C = fichier généré du dépôt, version live attendue V0, hash H0.

  1. Build. Context7 sur les nœuds touchés ; connexion n8n en mémoire par l'outil (aucun fichier de cookie, aucun secret dans wip/) ; source canonique modifiée (R-STD, plan/lot4.md §3) ; simplify ; tests verts ; candidat régénéré ; P-GIT 3-5.
  2. Rendu (lecture seule). deploy_guarded(..., apply=False) via le point d'entrée du paquet : garde editable_hash(live) == H0, versionId == activeVersionId == V0, liste des nœuds différents hors positions = exactement ceux attendus.
  3. Brouillon gardé, sans publier. deploy_guarded(..., apply=True, confirm_version=V0, publish=False), ou deploy_guarded_batch(..., publish=False) pour les paquets qui déploient par lot (coingecko_common/deploy.py) (modes ajoutés par le lot 4a) : PATCH, relecture du brouillon (versionId = V1, activeVersionId toujours V0, hash = C). La production continue sur V0. Avant le lot 4a : PATCH gardé équivalent (même lecture, même contrôle de version et de hash, PATCH, relecture), sans activate (#46 : un PATCH ne publie pas).
  4. Éditeur. Ouvrir W seulement après le PATCH (page rechargée, #31) ; une seule session navigateur à la fois (#54).
  5. Tidy Up natif sur tout le workflow, sélection vide ; aucun déplacement manuel ensuite.
  6. Note. Mettre à jour l'unique Workflow Notes si besoin, couleur par défaut, taille ajustée au contenu rendu (.n8n-sticky → firstElementChild.firstElementChild.scrollHeight, memory/feedback_n8n.md:27), au-dessus du bord gauche avec un espacement régulier.
  7. Autosave puis second Tidy Up : relire le brouillon par l'API avant et après ; zéro position changée. Piège n8n 2.47 (10/11) : Tidy Up peut alterner entre deux dispositions décalées de 48 px ; garder celle sur laquelle un Tidy Up ne bouge rien, sinon arrêter et documenter.
  8. Revue visuelle plein canvas : capture dans wip/<lot>/screenshots/ ; chemin heureux de gauche à droite, erreurs en dessous, note bien placée, pas de grand vide. Pour un workflow en ordre d'exécution v1, noter si Tidy Up a changé l'ordre vertical de branches parallèles (n8n exécute les branches de haut en bas) et vérifier que c'est sans effet.
  9. Fermer l'onglet de l'éditeur, puis restauration à l'octet : comparer le brouillon à C hors position (paramètres, connexions, réglages, credentials, code, prompts, contenu de la note). Si l'éditeur a normalisé quelque chose (déjà vu : appendAttribution=false, method: GET, onError retirés), PATCH des valeurs exactes en gardant les positions finales, relire, recomparer. Contrôler chaque nœud Telegram un par un.
  10. Publier une seule fois : POST /rest/workflows/W/activate {"versionId": <brouillon final>} (après 4a : publish_reviewed_draft, qui refait la comparaison de l'étape 9 avant d'activer).
  11. Relire : active: true, versionId == activeVersionId = version publiée.
  12. Réinjecter positions et note finales dans la source canonique (copie de structure, fixture ou builder), régénérer, mettre à jour version et hash de référence ; nouveau rendu : candidate_hash == live_hash. Commit de checkpoint (P-GIT 3-4).
  13. Vérifications propres au lot (succès, skip, retry, erreur, effets) en lecture seule.

Drain : seulement si le lot l'exige (même mécanisme que P-API étape 3, autour de la seule publication). Une publication ne coupe pas une exécution en cours : l'exécution garde la définition chargée à son départ, et les appels suivants chargent la version publiée (Context7 /n8n-io/n8n-docs : « Production executions always point to the currently published version » ; constat local memory/feedback_n8n.md:158-166). Un workflow à déclencheur Telegram ou webhook réenregistre son déclencheur à la publication.

Rollback.

5. Requêtes en lecture seule réutilisables

n8n (session unique par script : POST /rest/login est limité, memory/feedback_n8n.md:429).

Base produit (dans le conteneur API, timeout 60 docker exec -i event-engine-api python - <<'PY' ; from src.db import engine ; from sqlalchemy import text ; dans with engine.connect() as c:, exécuter d'abord SET TRANSACTION READ ONLY et SET LOCAL statement_timeout = '30s', puis la requête, puis c.rollback()) :