Lot 1, séquence A9 — Synchronisation et gel du contrat

1er octobre 2026. Mise en œuvre de la séquence A9 du plan du Lot 1. Décisions : EC-076, EC-077, EC-078. ADR 0040.

En bref

Un téléphone reçoit le périmètre de son agent, et seulement celui-là. Prouvé deux fois : par émulation des règles sur la base (automatique) et par le service PowerSync réel (pnpm sync:service).
Volume mesuré : 4,62 Mo pour le plus gros groupement (800 producteurs), 11,48 Mo dans le pire cas (2 000 producteurs sur un seul téléphone). Budget : 20 Mo.
Contrat d’API 1.0.0 gelé ; contrat des données synchronisées gelé dans infra/powersync/contrat-donnees.json.

Règles de synchronisation

Format bucket_definitions (EC-076). Fichier : infra/powersync/sync-config.yaml ; l’ancien fichier du prototype est conservé sous sync-config.prototype.yaml et se choisit par POWERSYNC_SYNC_CONFIG.

Compartiment	Paramètre	Contenu
`globales`	aucun	unités, devises, facteurs et leurs valeurs, taux de change, versions de pack
`organisation`	`organisation_id` du jeton	paramètres, campagnes, produits, attributs, référentiels, certificats
`contrats_actifs`	un compartiment par contrat d’achat actif	contrat, lignes, primes (via `prime.contrat_id`)
`perimetre_agent`	groupements de l’agent (`affectation_agent` en cours) et organisation	groupement, producteurs, parcelles, zones de cueillette, toutes les versions de polygone, statuts de conformité, soldes de capacité
`appareil`	`appareil_id` du jeton	résultats de commandes

Un contrat soldé ou résilié sort de contrats_actifs. Un agent sans affectation ne reçoit aucun périmètre.

Jamais descendus : numéro de pièce d’identité, chiffre d’affaires, fichiers, téléphone, géométrie binaire (geom ; seul geojson en texte), colonnes générées.

Colonnes générées (EC-077). PostgreSQL 16 ne réplique pas les colonnes générées stockées. Le téléphone calcule lui-même reste = capacité − consommé et incertitude = périmètre × précision / 100.

Versions de polygone. Une règle ne peut pas faire de « dernière version » : le téléphone reçoit toutes les versions de son périmètre et retient la plus récente. Le budget le permet (voir ci-dessous).

Données

Migration 20261001170000_lot1_a9_synchronisation.sql :

app.prime.contrat_id, repris de la ligne par un déclencheur (une valeur incohérente est refusée), pour filtrer les primes d’un contrat sans jointure ;
GRANT SELECT à biotrace_powersync sur 20 tables ;
publication powersync étendue à ces 20 tables.

Volume

pnpm demo:volume (transaction annulée, environ 4 minutes) porte le jeu à 2 000 producteurs (800, 700 et 500 par groupement, environ 3 000 parcelles) et mesure le JSON rendu par les règles, majoré de 50 % pour l’enveloppe du protocole.

Cas	Brut	Avec enveloppe
Plus gros groupement (800 producteurs)	3,08 Mo	4,62 Mo
Pire cas (2 000 producteurs)	7,65 Mo	11,48 Mo

Remesuré en L1-5 (compartiment module_membres_foncier) : 4,56 Mo et 11,38 Mo avec l’enveloppe, budget tenu.

Contrats gelés

API : VERSION_CONTRAT_API = 1.0.0. Tout ajout de route est une version mineure ; tout retrait ou changement incompatible, une version majeure. L’empreinte SHA-256 du document (hors numéro de version) est dans packages/schemas/contrat-gele.json ; le test gel.test.ts échoue si le document change sans changement de version (pnpm contrat:geler pour l’enregistrer). Le document est publié sur le site : /openapi.json.
Données synchronisées : colonnes et types de chaque table descendue, générés par pnpm sync:contrat et comparés au catalogue de la base par les tests.

Tests

Test	Ce qu’il vérifie
`db/tests/l1-a9.sql`	Tables publiées, lecture seule pour `biotrace_powersync`, clé `id`, `organisation_id` et `groupement_id`, comportement de `prime.contrat_id`
`infra/powersync/regles.test.mjs` (`pnpm sync:tester`)	Structure (un `SELECT`, une table, pas de jointure, colonnes explicites, aucune colonne interdite) ; périmètre par émulation sur deux groupements et deux organisations ; contrat de données
`infra/powersync/verifier-service.mjs` (`pnpm sync:service`)	Service réel : règles acceptées, compartiments attendus, aucune ligne hors périmètre, aucune donnée sensible
`gel.test.ts`	Version et empreinte du contrat d’API

Hors séance

Routes REST des services de A3 à A8 (en 1.x, additives, avec les écrans B3) ; essai sur un téléphone réel (Lot 3) ; EC-078 (la capacité n’est jugée qu’au traitement de la collecte par le serveur).