From d3a2c33b92cb00bd788e7544e38157cc825466ca Mon Sep 17 00:00:00 2001 From: Sylvain Duchesne Date: Thu, 9 Jul 2026 12:54:28 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20principe=20=E2=80=94=20le=20polyfill=20?= =?UTF-8?q?compense,=20il=20n'=C3=A9tend=20jamais?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Règle posée par l'utilisateur : la seule raison d'être du polyfill est de combler un retard d'implémentation NextGraph ou un bug. Aucune fonctionnalité additionnelle propre (pas de feature, d'observabilité, d'API de confort qui ne soit pas « NextGraph le fera nativement plus tard »). Corollaire : une compensation dont le gap n'est PAS exhibé sur le broker cible est du poids mort, pas du code défensif — à retirer. Co-Authored-By: Claude Opus 4.8 (1M context) --- packages/client/README.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/packages/client/README.md b/packages/client/README.md index 784db94..661b870 100644 --- a/packages/client/README.md +++ b/packages/client/README.md @@ -20,6 +20,18 @@ const set = useShape(MyShape, scope); // filtered to what the identity may rea await inbox.post(targetInbox, ref); // deposit (anticipated SDK API) ``` +## Principle — the polyfill compensates, it never extends + +**The polyfill's ONLY reason to exist is to bridge a NextGraph implementation gap +or a bug.** Every non-SDK surface must map to a capability NextGraph will provide +natively, and must fall away at that point. The polyfill MUST NOT add functionality +of its own — no bespoke features, no observability/tooling, no convenience API that +isn't strictly "NextGraph will do this natively later." The test for any proposed +addition: *does it compensate a real, exhibited NextGraph gap or bug?* If not, it +does not belong here — build it in the consumer application, not in the polyfill. +Corollary: a compensation whose gap is not actually exhibited on the target broker +is dead weight, not defensive code — it should be removed, not kept "just in case." + What the polyfill adds on top of the real SDK (each emulated for now, native as NextGraph matures): - Shared-wallet identity (one wallet for everyone; the current identity id is