brainclaw 1.21.0 → 1.22.0

package/dist/core/federation-projection.js

@@ -0,0 +1,336 @@
+/**
+ * Le projecteur et ses trois filets — fédération v2 (pln#651 étape 5, RFC §4).
+ *
+ * C'est ici que la table de classification devient EXÉCUTABLE. Trois classes, et
+ * « non classé » n'en est pas une quatrième : c'est un refus.
+ *
+ * ── POURQUOI TROIS FILETS ET NON UN SEUL ──────────────────────────────────────
+ * Établi par quatre critiques sur quatre pendant l'idéation, chacune par un angle
+ * différent :
+ *   (i)   Zod fait `.strip()` PAR DÉFAUT — un champ nouveau passe la validation en
+ *         silence, sans jamais lever ;
+ *   (ii)  un test couvre la SORTIE, pas la CONSTRUCTION — N projecteurs, un seul testé,
+ *         et les N-1 autres fuient (application littérale de trp#5a8fb7d9) ;
+ *   (iii) `{...entity, ciphertext}` compile parfaitement et déverse tout.
+ *
+ * Et le typage seul ne borne RIEN. `pushToCloud(payload: { id: string })` suivi d'un
+ * `JSON.stringify` sérialise chaque clé présente à L'EXÉCUTION : le typage structurel de
+ * TypeScript est une BORNE INFÉRIEURE sur ce que l'objet contient, jamais une borne
+ * supérieure. C'est la raison pour laquelle le filet 2 existe malgré le filet 1.
+ *
+ * FILET 1 — un builder nominal, marque de type non fabricable ailleurs, sélection
+ *           explicite champ par champ, JAMAIS de spread.
+ * FILET 2 — un parse `.strict()` à UN SEUL point de sortie que tout push traverse.
+ * FILET 3 — fixture golden byte-exacte + test de complétude sur l'inventaire.
+ *
+ * ── CE QUI RESTE VISIBLE, ÉCRIT ET NON MASQUÉ ─────────────────────────────────
+ * « Lane 3 » cache le libellé, pas le GRAPHE. Le nombre de lanes, la forme du graphe de
+ * dépendances et la cardinalité restent lisibles par le Cloud. C'est assumé : le board
+ * aveugle rend une structure, et une structure est une information. Le prétendre
+ * autrement serait mentir sur la garantie.
+ */
+import crypto from 'node:crypto';
+import { z } from 'zod';
+import { canonicalJson, canonicalSha256, b64url } from './federation-canonical.js';
+import { seal, HPKE_SUITE } from './federation-hpke.js';
+export const ENVELOPE_SCHEMA = 'brainclaw.federation-envelope/v1';
+export const AAD_PROTOCOL = 'brainclaw/federation/v1';
+/**
+ * Types d'entités PROJETABLES. Une famille absente de cette liste n'est pas « à faire
+ * plus tard » : son schéma entier est interdit de sortie (RFC §4.3). L'ajout d'une
+ * famille est un acte délibéré qui passe par la table de classification.
+ */
+export const FEDERATED_KINDS = [
+    'constraint', 'decision', 'trap', 'handoff', 'plan', 'plan_step', 'sequence',
+    'claim', 'candidate', 'runtime_note', 'inbox_message', 'assignment',
+    'agent_run', 'action_required', 'ai_task', 'runtime_event', 'lane_result',
+];
+// ── Champs INTERDITS DE SORTIR (RFC §4.2, classe 3) ──────────────────────────
+/**
+ * Ces noms ne doivent apparaître NI dans meta NI dans sealed. Leur présence fait échouer
+ * la projection — un refus, pas une troncature.
+ *
+ * POURQUOI UNE LISTE DE NOMS ICI ALORS QUE J'AI ÉCRIT AILLEURS QU'UNE LISTE DE NOMS NE
+ * SUFFIT PAS : elle ne suffit effectivement pas SEULE, et n'est pas seule. Le filet 1
+ * empêche déjà tout champ non explicitement sélectionné d'entrer dans meta, et le filet 2
+ * refuse toute clé inconnue à la sortie. Cette liste est un TROISIÈME contrôle qui vise
+ * le SCELLÉ — la seule partie que les deux autres filets ne peuvent pas inspecter,
+ * puisqu'ils la traitent comme opaque. Sans elle, `worktree_path` chiffré partirait quand
+ * même : chiffré n'est pas « autorisé à sortir ».
+ */
+export const FORBIDDEN_LEAF_NAMES = new Set([
+    'host_id', 'session_id', 'worktree_path', 'project_path', 'storage_dir', 'related_paths',
+    'command', 'shell', 'pid', 'provider_run_id', 'base_sha', 'cwd',
+    'api_key', 'apiKey', 'secret', 'token', 'password', 'private_key', 'privateKey',
+    'env', 'environment',
+]);
+/** Motifs de VALEURS trahissant un chemin local, quel que soit le nom du champ. */
+const LOCAL_PATH_PATTERNS = [
+    /^[A-Za-z]:[\\/]/, // C:\... ou C:/...
+    /^\/(?:home|Users|root)\//, // /home/x, /Users/x, /root/x
+    /\.brainclaw[\\/]worktrees/,
+];
+export class ProjectionRefused extends Error {
+    path;
+    constructor(message, path) {
+        super(message);
+        this.path = path;
+        this.name = 'ProjectionRefused';
+    }
+}
+/**
+ * Parcours RÉCURSIF refusant tout champ interdit, par son nom ou par la forme de sa
+ * valeur.
+ *
+ * Appliqué au CLAIR AVANT scellement, donc y compris à ce qui partira chiffré. Le RFC est
+ * explicite : la classe interdite est « absente de meta ET de sealed ». Un chemin de
+ * worktree chiffré reste une donnée qui a quitté l'hôte, et le jour où la clé fuit, elle
+ * a fui aussi. Le chiffrement protège le contenu ; il ne rend pas licite de l'envoyer.
+ */
+export function assertNoForbiddenLeaf(value, path = '$') {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === 'string') {
+        for (const pattern of LOCAL_PATH_PATTERNS) {
+            if (pattern.test(value)) {
+                throw new ProjectionRefused(`Chemin local détecté en ${path} — interdit de sortir, même scellé (RFC §4.2).`, path);
+            }
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => assertNoForbiddenLeaf(v, `${path}[${i}]`));
+        return;
+    }
+    if (typeof value === 'object') {
+        for (const [key, v] of Object.entries(value)) {
+            if (FORBIDDEN_LEAF_NAMES.has(key)) {
+                throw new ProjectionRefused(`Champ interdit '${key}' en ${path} — absent de meta ET de sealed (RFC §4.2).`, `${path}.${key}`);
+            }
+            assertNoForbiddenLeaf(v, `${path}.${key}`);
+        }
+    }
+}
+// ── FILET 2 : le schéma strict du point de sortie unique ─────────────────────
+/**
+ * `.strict()` PARTOUT, et c'est le point.
+ *
+ * Zod `.strip()` — le défaut — accepterait un objet porteur d'une clé inconnue et la
+ * retirerait SILENCIEUSEMENT du résultat. Le push passerait, et personne n'apprendrait
+ * qu'un champ non classé a été ajouté au projecteur. `.strict()` LÈVE, ce qui transforme
+ * l'oubli de classification en échec de CI plutôt qu'en fuite discrète.
+ */
+const CanonicalAadSchema = z.object({
+    protocol: z.literal(AAD_PROTOCOL),
+    cloud_project_id: z.string().min(1),
+    object_id: z.string().min(1),
+    base_rev: z.number().int().nonnegative(),
+    object_type: z.enum(FEDERATED_KINDS),
+    schema: z.literal(ENVELOPE_SCHEMA),
+}).strict();
+const PublicMetaSchema = z.object({
+    id_opaque: z.string().uuid(),
+    kind: z.enum(FEDERATED_KINDS),
+    status: z.object({
+        object: z.string().min(1),
+        sync: z.enum(['pending', 'synced', 'conflict']).optional(),
+    }).strict(),
+    priority: z.enum(['low', 'medium', 'high', 'critical']).optional(),
+    rank: z.number().int().optional(),
+    deps: z.array(z.object({ from: z.string().uuid(), to: z.string().uuid() }).strict()),
+    // Jour UTC, JAMAIS l'heure. Une heure précise trahit le rythme de travail d'une
+    // personne ; le jour ne dit que la cadence, ce que le RFC assume explicitement.
+    timestamp_bucket_jour: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+    base_rev: z.number().int().nonnegative(),
+    aad: CanonicalAadSchema,
+    // Ne contient NI nom NI empreinte de destinataire : la référence de paquet de clés
+    // aurait divulgué le roster, canal de fuite que l'idéation avait manqué.
+    wrap_hint: z.string().min(1),
+    transport: z.object({
+        operation_id: z.string().min(1),
+        content_hash: z.string().min(1),
+        idempotency_key: z.string().min(1),
+    }).strict(),
+}).strict();
+const SealedSchema = z.object({
+    alg: z.literal(HPKE_SUITE),
+    enc: z.string().min(1),
+    nonce: z.string().min(1),
+    ciphertext: z.string().min(1),
+}).strict();
+export const FederationEnvelopeSchema = z.object({
+    schema: z.literal(ENVELOPE_SCHEMA),
+    meta: PublicMetaSchema,
+    sealed: SealedSchema,
+    key_epoch: z.number().int().nonnegative(),
+    origin_sig: z.object({
+        alg: z.literal('Ed25519'),
+        key_id: z.string().min(1),
+        value: z.string().min(1),
+    }).strict(),
+}).strict();
+/** Jour UTC. La troncature est faite ICI pour qu'aucun appelant ne puisse l'oublier. */
+function dayBucket(when) {
+    const d = typeof when === 'string' ? new Date(when) : when;
+    if (Number.isNaN(d.getTime()))
+        throw new ProjectionRefused('Date invalide pour le bucket jour.', '$.occurredAt');
+    return d.toISOString().slice(0, 10);
+}
+/**
+ * Construit la projection publique — SÉLECTION EXPLICITE, CHAMP PAR CHAMP.
+ *
+ * Aucun spread nulle part dans cette fonction, et c'est délibéré : `{...input}` suffirait
+ * à déverser tout ce que l'appelant a mis dans l'objet. Chaque champ de meta est nommé
+ * ici ou n'existe pas. Ajouter un champ à `PublicMetaSchema` sans l'ajouter ici produit
+ * une erreur de compilation, et l'inverse un échec de parse `.strict()`.
+ *
+ * `priority` et `rank` ne sont posés QUE s'ils existent : l'absence d'un champ optionnel
+ * est SIGNIFICATIVE (RFC §3). Inventer `priority: 'medium'` pour un objet qui n'en porte
+ * pas créerait une fuite par normalisation — le Cloud croirait à une priorité choisie.
+ */
+export function toPublicProjection(input) {
+    const aad = {
+        protocol: AAD_PROTOCOL,
+        cloud_project_id: input.cloudProjectId,
+        object_id: input.idOpaque,
+        base_rev: input.baseRev,
+        object_type: input.kind,
+        schema: ENVELOPE_SCHEMA,
+    };
+    const meta = {
+        id_opaque: input.idOpaque,
+        kind: input.kind,
+        status: input.syncState
+            ? { object: input.statusObject, sync: input.syncState }
+            : { object: input.statusObject },
+        deps: (input.deps ?? []).map((d) => ({ from: d.from, to: d.to })),
+        timestamp_bucket_jour: dayBucket(input.occurredAt),
+        base_rev: input.baseRev,
+        aad,
+        wrap_hint: input.wrapHint,
+        transport: {
+            operation_id: input.operationId,
+            // Dérivés du CIPHERTEXT, jamais du clair (RFC §3.2). En v1, content_hash portait
+            // sur le corps sémantique en clair : le Cloud pouvait alors confirmer une
+            // devinette sur un contenu à faible entropie en comparant des hachages.
+            content_hash: canonicalSha256(input.sealed),
+            idempotency_key: '',
+        },
+    };
+    if (input.priority !== undefined)
+        meta.priority = input.priority;
+    if (input.rank !== undefined)
+        meta.rank = input.rank;
+    return meta;
+}
+/**
+ * LE SEUL point par lequel une enveloppe peut être produite.
+ *
+ * L'ordre des opérations est un contrat, pas un détail :
+ *   1. refus des champs interdits sur le CLAIR (avant qu'ils ne deviennent illisibles) ;
+ *   2. AAD canonique, lié au projet, à l'objet, à la révision et au type ;
+ *   3. scellement HPKE avec cet AAD exact ;
+ *   4. projection publique par le filet 1 ;
+ *   5. dérivés de transport calculés sur le CIPHERTEXT ;
+ *   6. signature d'origine sur meta ‖ sealed ‖ key_epoch ;
+ *   7. parse `.strict()` — le filet 2 — qui refuse toute clé inconnue.
+ *
+ * Inverser 1 et 3 laisserait passer un champ interdit dans le blob chiffré.
+ */
+export function buildEnvelope(params) {
+    // (1) Le contrôle porte sur le clair, y compris ce qui sera scellé.
+    assertNoForbiddenLeaf(params.content, '$.content');
+    // (2) AAD comme STRUCTURE canonique et non concaténation ambiguë : « a|b » et « a|b »
+    // issus de découpages différents produisent la même chaîne, donc deux contextes
+    // distincts indiscernables.
+    const aad = {
+        protocol: AAD_PROTOCOL,
+        cloud_project_id: params.cloudProjectId,
+        object_id: params.idOpaque,
+        base_rev: params.baseRev,
+        object_type: params.kind,
+        schema: ENVELOPE_SCHEMA,
+    };
+    const aadBytes = new TextEncoder().encode(canonicalJson(aad));
+    // (3)
+    const sealed = seal({
+        recipientPublicKeyPem: params.recipientPublicKeyPem,
+        plaintext: new TextEncoder().encode(canonicalJson(params.content)),
+        aadCanonicalBytes: aadBytes,
+    });
+    // (4)
+    const meta = toPublicProjection({
+        kind: params.kind,
+        idOpaque: params.idOpaque,
+        cloudProjectId: params.cloudProjectId,
+        baseRev: params.baseRev,
+        statusObject: params.statusObject,
+        syncState: params.syncState,
+        priority: params.priority,
+        rank: params.rank,
+        deps: params.deps,
+        occurredAt: params.occurredAt,
+        wrapHint: params.wrapHint,
+        operationId: params.operationId,
+        sealed,
+    });
+    // (5) idempotency_key = SHA-256(canonical(sealed) || operation_id || origin_sig.key_id).
+    // CLEFÉE par l'identité du signataire : deux agents qui pousseraient le même contenu
+    // n'auraient pas la même clé, donc le Cloud ne peut pas déduire qu'ils poussent la
+    // même chose.
+    meta.transport.idempotency_key = b64url(new Uint8Array(crypto.createHash('sha256')
+        .update(canonicalJson(sealed), 'utf-8')
+        .update(params.operationId, 'utf-8')
+        .update(params.originKeyId, 'utf-8')
+        .digest()));
+    // (6) L'entrée couvre alg, enc, nonce ET ciphertext, plus key_epoch — pas seulement
+    // « meta || ciphertext ». Le raccourci ne couvrirait pas les paramètres permettant
+    // d'INTERPRÉTER le ciphertext, qu'un Cloud pourrait alors modifier sans casser la
+    // signature.
+    const signingInput = Buffer.concat([
+        Buffer.from('brainclaw/federation-envelope/v1\0', 'utf-8'),
+        Buffer.from(canonicalJson(meta), 'utf-8'),
+        Buffer.from(canonicalJson(sealed), 'utf-8'),
+        Buffer.from(canonicalJson(params.keyEpoch), 'utf-8'),
+    ]);
+    const signature = crypto.sign(null, signingInput, crypto.createPrivateKey(params.originPrivateKeyPem));
+    const envelope = {
+        schema: ENVELOPE_SCHEMA,
+        meta,
+        sealed,
+        key_epoch: params.keyEpoch,
+        origin_sig: { alg: 'Ed25519', key_id: params.originKeyId, value: signature.toString('base64url') },
+    };
+    // (7) FILET 2 — fail-closed. Une clé inconnue lève ici plutôt que de partir sur le fil.
+    return FederationEnvelopeSchema.parse(envelope);
+}
+/**
+ * Octets exacts sur lesquels porte la signature d'origine.
+ *
+ * Exporté pour que le VÉRIFICATEUR les reconstruise avec la même fonction que
+ * l'émetteur. Deux reconstructions indépendantes est précisément le défaut qui a rendu
+ * l'attestation d'appairage insatisfiable côté Cloud : le vérificateur fabriquait un
+ * champ que le signataire ne pouvait pas connaître.
+ */
+export function originSigningInput(meta, sealed, keyEpoch) {
+    return Buffer.concat([
+        Buffer.from('brainclaw/federation-envelope/v1\0', 'utf-8'),
+        Buffer.from(canonicalJson(meta), 'utf-8'),
+        Buffer.from(canonicalJson(sealed), 'utf-8'),
+        Buffer.from(canonicalJson(keyEpoch), 'utf-8'),
+    ]);
+}
+// ── Ids opaques ──────────────────────────────────────────────────────────────
+/**
+ * Ids RE-ROULÉS en UUID v4, mapping local↔cloud gardé LOCAL.
+ *
+ * Pourquoi ne pas simplement hacher l'id local : un hachage est déterministe, donc le
+ * même objet exporté vers deux projets Cloud produirait le même identifiant, et un
+ * observateur corrélerait les deux projets. Un UUID aléatoire par projet coupe cette
+ * corrélation — c'est le sens de « stable dans un projet Cloud, pas cross-projet »
+ * (RFC §4.1).
+ */
+export function newOpaqueId() {
+    return crypto.randomUUID();
+}
+//# sourceMappingURL=federation-projection.js.map

package/dist/core/federation-relay.js

@@ -0,0 +1,223 @@
+/**
+ * Commandes cloud matérialisées localement — le RELAIS (pln#651 étape 7, dec#154).
+ *
+ * ── CE QUI SURVIT INTACT AU CHIFFREMENT ───────────────────────────────────────
+ * À écrire d'emblée, pour qu'on ne « résolve » pas un faux problème : `base_rev` compare
+ * un IDENTIFIANT DE RÉVISION, pas du contenu. L'idempotence, `operation_id`, la
+ * provenance et l'audit ne référencent que des ids et des actions. Rien de tout cela n'a
+ * besoin de lire le clair, et le chiffrement ne gêne donc en rien ce module.
+ *
+ * LE RELAIS N'ÉCRIT JAMAIS DE CONTENU. Le contenu reste en écriture depuis le local
+ * uniquement. Une commande venue du dashboard porte sur des MÉTADONNÉES : priorité,
+ * ordre, rang, statut, métadonnées de roadmap. C'est la conséquence directe de dec#154 —
+ * « le Cloud est une projection et un relais ; le local est la source de vérité ».
+ *
+ * ── LA TROISIÈME CLASSE D'APPELANTS (dec#155) ─────────────────────────────────
+ * Le relais cloud n'a NI session, NI cwd, NI contexte ambiant : seulement un id d'entité
+ * et un `base_rev`. C'est le cas le plus pur du routage autoritatif par l'entité, déjà en
+ * place côté core depuis la 1.21.0.
+ *
+ * NE PAS RÉINVENTER DE RÉSOLUTION AMBIANTE POUR LUI. La tentation est réelle — « si le
+ * projet n'est pas précisé, prendre le projet actif » — et c'est exactement la dérive que
+ * pln#648/649 ont corrigée pour le routage local. Une commande sans cible résoluble est
+ * REFUSÉE, jamais devinée.
+ *
+ * ── LES CONFLITS ──────────────────────────────────────────────────────────────
+ * Présentés avec une proposition de résolution, JAMAIS de last-write-wins silencieux. Et
+ * c'est le contrat de refus de T3 exprimé sur un autre transport : une divergence PROUVÉE
+ * refuse et nomme ; une ABSENCE retombe sur la réponse ambiante. Le même mécanisme, pas
+ * un second.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { memoryDir, writeFileAtomic } from './io.js';
+import { nowISO } from './ids.js';
+import { canonicalJson } from './federation-canonical.js';
+import { logger } from './logger.js';
+const JOURNAL_DIR = ['coordination', 'federation', 'commands'];
+/**
+ * Les seuls champs qu'une commande cloud peut toucher.
+ *
+ * LISTE FERMÉE ET NON EXTENSIBLE PAR CONFIGURATION : c'est la traduction exécutable de
+ * « le relais n'écrit jamais de contenu ». Ajouter `text` ou `description` ici ferait du
+ * Cloud une source d'écriture de contenu et retournerait dec#154.
+ */
+export const RELAYABLE_FIELDS = ['priority', 'rank', 'status'];
+export const CloudCommandSchema = z.object({
+    /** Identité de l'opération, créée par l'émetteur et REJOUÉE à l'identique en cas de retry. */
+    operation_id: z.string().min(1),
+    /** Cible : un id d'entité opaque. Pas de projet, pas de cwd, pas de session (dec#155). */
+    object_id: z.string().min(1),
+    /** Révision sur laquelle l'émetteur s'appuie. Un décalage produit un conflit VISIBLE. */
+    base_rev: z.number().int().nonnegative(),
+    field: z.enum(RELAYABLE_FIELDS),
+    value: z.union([z.string(), z.number()]),
+    /** Identité Ed25519 de l'émetteur — audité, pas cru sur parole. */
+    issued_by: z.string().min(1),
+    issued_at: z.string().min(1),
+}).strict();
+function journalDir(cwd) {
+    return path.join(memoryDir(cwd), ...JOURNAL_DIR);
+}
+/**
+ * Le journal est indexé par `operation_id` — c'est ce qui rend le rejeu inoffensif.
+ *
+ * Un index par (object_id, base_rev) ne suffirait pas : deux commandes distinctes peuvent
+ * légitimement viser la même révision d'un même objet (changer la priorité, puis le rang).
+ */
+function entryPath(cwd, operationId) {
+    // Le nom de fichier est assaini : un operation_id venu du réseau ne doit pas pouvoir
+    // écrire hors du répertoire du journal via '../'.
+    const safe = operationId.replace(/[^A-Za-z0-9_.-]/g, '_');
+    return path.join(journalDir(cwd), `${safe}.json`);
+}
+export function loadJournalEntry(cwd, operationId) {
+    const filepath = entryPath(cwd, operationId);
+    if (!fs.existsSync(filepath))
+        return undefined;
+    try {
+        return JSON.parse(fs.readFileSync(filepath, 'utf-8'));
+    }
+    catch (err) {
+        // Une entrée illisible n'est PAS traitée comme absente : la traiter ainsi ferait
+        // réappliquer une commande déjà appliquée, ce que tout ce module cherche à empêcher.
+        logger.warn(`Entrée de journal illisible (${operationId}) : ${err instanceof Error ? err.message : String(err)}`);
+        // `cause` conservée : sans elle, un opérateur voit « journal corrompu » sans savoir
+        // si c'est un JSON tronqué, un encodage cassé ou un disque plein.
+        throw new Error(`Journal corrompu pour l'opération ${operationId} — refus d'appliquer à l'aveugle.`, { cause: err });
+    }
+}
+function writeEntry(cwd, entry) {
+    const filepath = entryPath(cwd, entry.operation_id);
+    fs.mkdirSync(path.dirname(filepath), { recursive: true });
+    writeFileAtomic(filepath, `${JSON.stringify(entry, null, 2)}\n`);
+}
+/**
+ * Applique une commande cloud au journal local.
+ *
+ * `resolveLocalRev` est INJECTÉ plutôt que lu ici : ce module ne connaît pas le stockage
+ * des entités, et lui donner cette connaissance en ferait un second chemin d'écriture sur
+ * la mémoire — précisément ce que « le relais n'écrit jamais de contenu » interdit. Il
+ * écrit le journal ; c'est l'appelant qui, à partir du journal, applique un changement de
+ * métadonnée par la voie locale normale.
+ *
+ * TROIS ISSUES ET AUCUN ÉCRASEMENT SILENCIEUX :
+ *   applied   — base_rev correspond, l'effet est enregistré ;
+ *   duplicate — operation_id déjà connu, aucun second effet (idempotence) ;
+ *   conflict  — base_rev périmé : l'entrée est écrite en état `conflict` AVEC une
+ *               proposition, et attend une décision humaine.
+ */
+export function applyCloudCommand(params) {
+    const parsed = CloudCommandSchema.safeParse(params.raw);
+    if (!parsed.success) {
+        return { status: 'refused', reason: `commande invalide : ${parsed.error.issues.map((i) => i.path.join('.')).join(', ')}` };
+    }
+    const cmd = parsed.data;
+    // IDEMPOTENCE D'ABORD. Rejouer une commande déjà appliquée doit être un no-op, y compris
+    // si la révision locale a changé entre-temps — sinon un retry réseau produirait un
+    // conflit fantôme sur une opération pourtant déjà réussie.
+    const existing = loadJournalEntry(params.cwd, cmd.operation_id);
+    if (existing) {
+        return { status: 'duplicate', entry: existing };
+    }
+    const localRev = params.resolveLocalRev(cmd.object_id);
+    if (localRev === undefined) {
+        // TROISIÈME CLASSE D'APPELANTS (dec#155) : pas de repli ambiant. Un objet inconnu est
+        // refusé et nommé, jamais rattaché au « projet actif » par défaut.
+        return { status: 'refused', reason: `objet '${cmd.object_id}' inconnu localement — aucune résolution ambiante pour le relais cloud (dec#155).` };
+    }
+    const base = {
+        operation_id: cmd.operation_id,
+        object_id: cmd.object_id,
+        base_rev: cmd.base_rev,
+        field: cmd.field,
+        value: cmd.value,
+        issued_by: cmd.issued_by,
+        issued_at: cmd.issued_at,
+        materialized_at: nowISO(),
+    };
+    if (cmd.base_rev !== localRev) {
+        // CONFLIT VISIBLE, jamais un écrasement. La proposition est formulée ici parce que
+        // c'est ici qu'on connaît les deux révisions ; la rendre plus tard obligerait
+        // l'interface à re-déduire ce que le journal savait déjà.
+        const entry = {
+            ...base,
+            state: 'conflict',
+            conflict: {
+                local_rev: localRev,
+                proposal: localRev > cmd.base_rev
+                    ? `Le local a avancé (rév. ${localRev} > ${cmd.base_rev}). Rejouer la commande sur la révision ${localRev}, ou l'abandonner si le changement local la rend caduque.`
+                    : `La commande s'appuie sur une révision (${cmd.base_rev}) postérieure au local (${localRev}) — le local a probablement été restauré. Vérifier avant d'appliquer.`,
+            },
+        };
+        writeEntry(params.cwd, entry);
+        return { status: 'conflict', entry };
+    }
+    const entry = { ...base, state: 'pending' };
+    writeEntry(params.cwd, entry);
+    return { status: 'applied', entry };
+}
+/** Marque une entrée synchronisée une fois l'effet local réellement appliqué. */
+export function markCommandSynced(cwd, operationId) {
+    const entry = loadJournalEntry(cwd, operationId);
+    if (!entry)
+        return false;
+    writeEntry(cwd, { ...entry, state: 'synced' });
+    return true;
+}
+/**
+ * Résout un conflit par une DÉCISION EXPLICITE.
+ *
+ * Il n'existe volontairement aucune résolution automatique : dec#154 dit « jamais de
+ * last-write-wins silencieux », et un mode « auto » finirait par être le défaut.
+ */
+export function resolveCommandConflict(params) {
+    const entry = loadJournalEntry(params.cwd, params.operationId);
+    if (!entry || entry.state !== 'conflict')
+        return undefined;
+    const resolved = {
+        ...entry,
+        state: params.decision === 'accept' ? 'pending' : 'synced',
+        conflict: undefined,
+    };
+    writeEntry(params.cwd, resolved);
+    return resolved;
+}
+/** Entrées du journal dans un état donné — sert à rendre les conflits visibles. */
+export function listCommands(cwd, state) {
+    const dir = journalDir(cwd);
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            const entry = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf-8'));
+            if (!state || entry.state === state)
+                out.push(entry);
+        }
+        catch {
+            logger.warn(`Entrée de journal ignorée (illisible) : ${name}`);
+        }
+    }
+    return out.sort((a, b) => a.materialized_at.localeCompare(b.materialized_at));
+}
+/**
+ * Empreinte d'audit d'une commande — ce qui a été demandé, par qui, sur quelle révision.
+ *
+ * Calculée sur les octets CANONIQUES pour qu'elle soit reproductible des deux côtés : un
+ * audit qu'on ne peut pas recalculer identiquement ne prouve rien.
+ */
+export function commandAuditDigest(cmd) {
+    return canonicalJson({
+        operation_id: cmd.operation_id,
+        object_id: cmd.object_id,
+        base_rev: cmd.base_rev,
+        field: cmd.field,
+        value: cmd.value,
+        issued_by: cmd.issued_by,
+    });
+}
+//# sourceMappingURL=federation-relay.js.map