docs: drainer les demandes de ng-helpers dans l-engagement, en 1.0.0-dev.15

Patch: aucune signature ne change, aucun comportement ne bouge, seul ce que
le contrat DIT bouge - c-est le seul canal dont dispose une demande.

Surface
- une forme ShEx complete, celle de examples/notebook/app.ts, plus l-argument
  de type qui type l-instantane (sans lui, T vaut BaseType - mesure au tsc)
- initNg jette son premier argument et passe le ng publie a sa place (mesure:
  une sentinelle en position 0 n-arrive jamais, et ce qui arrive est === ng)

Guarantees
- une requete ancree refuse a voix haute le document qu-elle ne peut pas lire,
  au lieu de l-avaler: vrai depuis 1.0.0-dev.8, dit seulement dans sa note
- quelles lectures atteignent un document de store public depuis sa seule
  reference, et lesquelles non, enonce en un seul endroit

Non-guarantees
- ce qu-etait vraiment la panne orm_start_graph is not a function: l-enveloppe
  ng de ce paquet, corrigee en 1.0.0-dev.7, et non le moteur refusant la forme
- l-avalement amont epingle sur l-artefact livre (@ng-org/orm 0.1.2-alpha.21,
  dist/connector/RdfOrmSubscription.js) et non sur le checkout cite
- une liste << Asked for, not decided >>: useShape obligatoire, garde de type
  NURI, echappement, ecriture de triplets au-dessus de sparqlUpdate, store
  d-un document deja tenu, issue par depot

Change policy
- le tag polyfill/v<version> est le pin, et les tags retardent sur les
  versions: le plus recent cut est polyfill/v1.0.0-dev.3
This commit is contained in:
Sylvain Duchesne
2026-10-01 15:56:16 +02:00
parent 751d8d26e6
commit ec3900077b
3 changed files with 77 additions and 8 deletions
+1 -1
View File
@@ -294,7 +294,7 @@ public close(): void;
So the constraint on the bet: the target can already answer "synced?" (`readyPromise`), and `useShape` today returns "an empty set, if still loading" (its own doc comment, `useShape.ts:29-31`) — indistinguishable from synced-empty. `useShapeQuery` surfaces the distinction with a TanStack-`useQuery`-minimal vocabulary (`isPending`/`isSuccess`/`isError`). That is **not** a shape of this library's choosing any more: NextGraph's developers have stated it is the direction, and the statement is on record in `.project/rules/nextgraph/surface-mirrors-the-sdk.md` with its date — which is what the symbol's `announced-not-written` annotation cites. Deviating toward an announced target is alignment; the distinction it teaches (pending is not empty) is target-expressible either way.
**But `readyPromise` answers two of those three questions, not three — VERIFIED 2026-08-17, and it bears on `isError` specifically.** It is constructed with `resolve` alone (`new Promise<void>((resolve) => { this.resolveReady = resolve; })`, `GraphOrmSubscription.ts` constructor), nothing anywhere rejects it, and `resolveReady()` is called on one path only — the arrival of initial data. The subscription that fails does not settle it: `orm_start_graph` is awaited inside a `try` whose `catch` is `console.error(e)`, so the promise stays pending forever and every `await this.readyPromise_` behind it hangs. Upstream's "I could not find out" IS its "still pending". So `isPending` and `isSuccess` map onto something real at level 3, while `isError` has **no counterpart at any level** — it is this library's third state, and the reason it exists is that swallowing a failed read into a plausible-looking result is the shape that took this project a week to close everywhere else. A consumer should keep reading it; if the future hook ships without one, the failure is the pending that never ends, which is a worse thing to have to render, not a reason to have learned less.
**But `readyPromise` answers two of those three questions, not three — VERIFIED 2026-08-17, and it bears on `isError` specifically.** It is constructed with `resolve` alone (`new Promise<void>((resolve) => { this.resolveReady = resolve; })`, `GraphOrmSubscription.ts` constructor), nothing anywhere rejects it, and `resolveReady()` is called on one path only — the arrival of initial data. The subscription that fails does not settle it: `orm_start_graph` is awaited inside a `try` whose `catch` is `console.error(e)`, so the promise stays pending forever and every `await this.readyPromise_` behind it hangs. **Re-verified 2026-10-01 against what SHIPS**, not only against the cited checkout: in the installed `@ng-org/orm@0.1.2-alpha.21` that file is `dist/connector/RdfOrmSubscription.js`, and all three facts hold there unchanged. That is the artifact the published contract now cites, because it is the one an application runs. Upstream's "I could not find out" IS its "still pending". So `isPending` and `isSuccess` map onto something real at level 3, while `isError` has **no counterpart at any level** — it is this library's third state, and the reason it exists is that swallowing a failed read into a plausible-looking result is the shape that took this project a week to close everywhere else. A consumer should keep reading it; if the future hook ships without one, the failure is the pending that never ends, which is a worse thing to have to render, not a reason to have learned less.
---