Sylvain Duchesne
737729c9ce
Le nom @ng-eventually/sdk entrait en collision avec le SDK de NextGraph, dont ce paquet est justement un polyfill. Impossible d'écrire « le SDK » sans lever l'ambiguïté à chaque phrase — et le contrat publié, lu par une application, était le pire endroit pour laisser traîner ça. packages/sdk → packages/polyfill, @ng-eventually/sdk → @ng-eventually/polyfill, contract_sdk-surface → contract_polyfill-surface, e2e/sdk-entry.ts → e2e/polyfill-entry.ts, docs/sdk-reference.md → docs/polyfill-reference.md. Les occurrences de « SDK » qui désignent celui de NextGraph restent intactes, y compris les chemins dans nextgraph-rs (sdk/js/orm, sdk/js/web). Le tri s'est fait occurrence par occurrence, pas par substitution. Le contrat énonce désormais son identité en une phrase : « This package is a polyfill of NextGraph's SDK. »
3.2 KiB
type, summary
| type | summary |
|---|---|
| knowledge | The two fates a published symbol can have, and why the deletion list is now carried by a block and a test rather than by an import path |
What an application deletes at migration, and what it keeps
Every published symbol has exactly one of two fates, and knowing which is the whole point of this boundary.
Replaced in place. The build alias resolving @ng-eventually/polyfill is removed, the import resolves to the real SDK, and the application's code is unchanged. This is almost everything: ng, useShape, watchShape, init, initNg, readUnion, subscribeDoc(s), docs.*, inbox.*, storeRegistry.*, and the types.
Deleted. The symbol has no counterpart at any level of the target, exists only because one shared wallet hosts every user, and goes with its call site. Today that is configure and its config type.
ensureIdentity sits between the two and is worth stating precisely: its substance is scaffolding — a barrier that hands out a shared wallet file and takes an identifier, a step that exists only because users share a wallet — while its call site survives, because an application still awaits a session before it renders. Its signature was designed for that: it takes no identifier, so the line does not change the day the wallet supplies the identity and the barrier stops appearing.
Why the deletion list is not an import path any more
There were two entry points until 2026-08-07, . and ./polyfill, and the second one carried a signal worth naming: what you import from that path is exactly what you will delete. That was a mechanical guarantee — the compiler produced the list.
Merging them lost it. Nothing at an import line now distinguishes configure, which goes away, from docs, which is replaced. Three things carry it instead, and it is worth knowing that only the last two are enforced:
- the
POLYFILL-ERAblock in the package's entry module, which is the deletion list, kept short by construction; docs/api-contract.md, which rules on every symbol with an epistemic label (PASSTHROUGH / LEVEL-1 SHAPE / ASSUMPTION / NO COUNTERPART) and whose export inventory is pinned by a test — so it cannot go stale quietly, which a hand-kept list would;- the names themselves, each built from the target's own vocabulary or carrying a marker saying why it exists only here, pinned by the same test.
The trade was deliberate and it is a real reduction in enforcement: a documentary signal where a mechanical one used to be. To verify the pinning is doing its job, look for the vocabulary test beside the package's other tests — it compares the contract's inventory against the entry's real exports, in both directions, and it caught five drifted sections the day it was extended to the rulings.
The direction of travel
The polyfill-era list only shrinks. It has gone from four published calls to one, and each removal was a symbol an application should never have had: naming its own identity, awaiting the connection, wiring a second bootstrap, reaching a machinery accessor. A symbol added to that block is a promise to delete it later — so the question at every addition is whether the application genuinely needs it, or whether the library is passing on a problem of its own.