Reconnexion/ng-eventually
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: regler la dette doc, et rapatrier les declarations de ng-helpers

Browse Source
This commit is contained in:
Sylvain Duchesne
2026-10-01 12:20:18 +02:00
parent 0cebf6e29a
commit 4c1801f6ee
5 changed files with 155 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.project/concepts/app-contract/knowledge_what-an-app-deletes-at-migration.md
+6 -4
View File
@@ -7,11 +7,13 @@ summary: The two fates a published symbol can have, and why the deletion list is
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 the types.
**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. That is the reason this leaf exists — a symbol whose fate is asserted rather than checked is how the list goes wrong.
**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 its config type.
**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.
@@ -29,4 +31,4 @@ The trade was deliberate and it is a real reduction in enforcement: a documentar
## 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.
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.