docs: dire partout que la lecture par lot n'existe plus

Le contrat publie et l'api-contract etaient traites avec le retrait lui-meme ;
restaient les documents qui decrivaient readUnion comme la primitive de
lecture du paquet, ou qui nommaient le module disparu.

Ce que les lecteurs apprennent maintenant : lire un document, c'est
docs.sparqlQuery ancre dessus, et lire plusieurs documents, c'est cet appel
une fois par document -- avec la decision sur une lecture qui echoue ecrite
au point d'appel. Deux consequences sont dites plutot que decouvertes : une
lecture refusee leve au lieu de rendre une liste vide, et les sujets sous le
prefixe reserve urn:ng-eventually: reviennent dans le resultat, a l'appelant
de les ignorer -- sans aucun gain de droits, les deux registres qu'un
document ordinaire porte etant l'adresse de sa boite et, pour un document
public, la cle que son magasin sert deja a qui la demande.

Les briefs dates ne sont pas touches : ils decrivent un etat de juillet, et
le reecrire falsifierait ce qui avait ete decide alors.
This commit is contained in:
Sylvain Duchesne
2026-09-21 14:11:35 +02:00
parent 0c21adebf2
commit 0a2b8b1fbf
29 changed files with 90 additions and 77 deletions
+11 -12
View File
@@ -173,14 +173,13 @@ In `@ng-eventually/polyfill` the one-shot read is exposed as:
- **`docs.sparqlQuery(sid, query, base?, anchor?)`** — a raw anchored SPARQL query
([`../src/surface/docs.ts`](../src/surface/docs.ts)). `anchor` = the document NURI to read; the
anchor restricts the query to that one repo's graph.
- **`readUnion(docs)`** — read a **bounded, by-need set** of document NURIs,
each with its own anchored query, grouped per subject
([`../src/surface/read-model.ts`](../src/surface/read-model.ts)). This is the polyfill's listing
primitive (see [§ Current emulation status](#current-emulation-status) and
[`read-model.md`](../../../docs/read-model.md)).
`readUnion(docs)` sat above this until `1.0.0-dev.8` and is **gone**: it was this call
once per document plus a batch policy nothing upstream answers. Reading a bounded set
of documents is this call in a loop, and what one unreadable document does to the rest
is decided at the call site (see [`read-model.md`](../../../docs/read-model.md)).
One-shot reads do not re-render on change. To stay live over a one-shot read you must
re-run it on a change **signal** (e.g. re-call `readUnion` when a `doc_subscribe`
re-run it on a change **signal** (e.g. re-run the anchored query when a `doc_subscribe`
fires) — a manual assembly that exists only because of the emulation gap below; the
finished contract is `useShape`.
@@ -303,11 +302,11 @@ from the reactive contract:
`engine/verifier/src/request_processor.rs` `resolve_target` →
`self.repos.get(...).ok_or(RepoNotFound)`; see
[`nextgraph-current-state.md`](../../../docs/nextgraph-current-state.md) § *The ORM
fan-out hang*). So the lib reads entity lists with **`readUnion`** — a
bounded set of one-shot anchored `sparql_query`s
([`read-model.md`](../../../docs/read-model.md)) — and reassembles reactivity by
**re-querying on a change signal** (a lightweight `doc_subscribe` / single-store ORM
used only as a *signal* source, then re-run `readUnion`). `useShape` remains valid
fan-out hang*). So the lib reads entity lists as **one anchored `sparql_query` per
document** ([`read-model.md`](../../../docs/read-model.md)) — and reassembles
reactivity by **re-querying on a change signal** (a lightweight `doc_subscribe` /
single-store ORM used only as a *signal* source, then re-run the reads). `useShape`
remains valid
for a **single already-opened document**; it is the per-entity **fan-out** that is
unfit today.
@@ -334,7 +333,7 @@ from the reactive contract:
`ng.doc_subscribe`), the subscription callback appears NOT to fire for its OWN
local commit in the same session — so the reactive re-read chain
([`../src/surface/use-shape-query.ts`](../src/surface/use-shape-query.ts) `useShapeQuery` → `reread` →
[`../src/surface/read-model.ts`](../src/surface/read-model.ts) `readUnion`) never runs, and
the anchored per-document read) never runs, and
consumers keep the STALE value until the next connection delivers a fresh
initial `State`. **Remote** commits DO push correctly (verified: cross-browser
reactive update works). A code review verified the consumer wiring is correct,