Sylvain Duchesne
5.4 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, useShapeQuery, init, initNg, getObjects, insertObject, subscribeDoc(s), docs.*, inbox.*, storeRegistry.*, and every type a published signature actually uses - a type that no signature uses has the third fate below, not this one.
A third fate exists and is not one of the two: withdrawn before migration. readUnion and UnionSubject were listed above as replaced in place, and they were never going to be: a batch over N anchored queries has no counterpart at any level, so nothing would have resolved to it. They left the surface in 1.0.0-dev.8, and an application reads one document with docs.sparqlQuery instead. Schema and DeepSignalSet followed in 1.0.0-dev.12, for a different reason worth keeping apart: not that the target lacks a counterpart - it has both - but that no published signature here used them, so they were surface an application could name and never needed. That is the reason this leaf exists - a symbol whose fate is asserted rather than checked is how the list goes wrong, and the two withdrawals show the question is asked twice: does the target carry it, and does our own surface need it.
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 EventuallyConfig, the five types that describe that config's fields, and ShapeObservable.
ShapeObservable is the instructive one, because its fate is COUPLED rather than independent. It is what useShapeQuery returns, and it is not a framework adapter: it carries the capability filter behind getSnapshot and the capability-arrival re-publish keyed on the held-caps signal. A capability arrives mid-session only because the wallet is shared, so in the target there is nothing to filter and no arrival to react to - and an announced hook returning a snapshot has nowhere to hang such a subscription because it needs none. It therefore goes exactly when the shared wallet goes, not before and not on its own. Read the deletion list as naming one migration there, not four removals.
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 entries 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 CALLS only shrink - from four to one, each removal a symbol an application should never have had: naming its own identity, awaiting the connection, wiring a second bootstrap, reaching a machinery accessor. The BLOCK does not: it grew by six type entries in 1.0.0-dev.13 and -dev.14, when five config field types and ShapeObservable were found sitting in the SDK-shaped section while honestly annotated as having no counterpart. That was a correction, not a regression - the block got longer because it got true - and the distinction matters, because reading monotonicity as the invariant is how a misplaced symbol stays misplaced to protect a trend. 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.