feat!: la famille ORM est publiee enveloppee, et le ng publie cesse de rendre des promesses

packages/polyfill/docs/polyfill-reference.md

@@ -163,6 +163,13 @@ computes a result and returns once (`sparql_query`,
 
 In `@ng-eventually/polyfill` the one-shot read is exposed as:
 
+- **`getObjects(shapeType, config)`** - the ORM's own one-shot read, by SHAPE, over the
+  same `Scope` axes `useShapeQuery` takes plus `where` and `orderBy`
+  ([`../src/surface/orm.ts`](../src/surface/orm.ts)). This is the typed one, and the one
+  to reach for first. What comes back is DETACHED - a clone - so mutating or deleting an
+  item of it reaches nothing; and it is filtered by what you hold, so another identity's
+  objects are not in it. Import it from here and never from `@ng-org/orm`: one wallet
+  hosts every identity, and the unwrapped call returns everybody's objects.
 - **`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.
@@ -188,10 +195,22 @@ document model, so briefly:
   ([`../src/surface/docs.ts`](../src/surface/docs.ts)) — mirrors `ng.doc_create`. **One document = one
   repo** (`did:ng:o:<RepoID>`); there is no separate `Document` type.
 - **Write into it:** `docs.sparqlUpdate(sid, query, anchor)` — a SPARQL
-  `INSERT/DELETE` scoped to the anchor document's graph. Or, at the ORM layer, the ORM
-  update primitives (`graph_orm_update`). A write is a **commit** on the document's
+  `INSERT/DELETE` scoped to the anchor document's graph. Or, at the ORM layer,
+  `insertObject(shapeType, object)` for one typed object with its `@graph` set
+  ([`../src/surface/orm.ts`](../src/surface/orm.ts)), or a mutation of the live set a
+  shape query handed back - `set.add(...)`, `set.delete(...)`, assigning a property - which
+  the ORM batches into `graph_orm_update`. A write is a **commit** on the document's
   branch — which is exactly what every `useShape` subscriber over that document is
   pushed.
+- **Remove an object:** delete it from the LIVE set (`set.delete(item)`, the item the set
+  is holding - reached by iterating it, by `.first()` or by `.getBy(graph, subject)`).
+  There is no `deleteObject` and no document deletion at any level; what the engine
+  removes is the SHAPE's declared predicates on that subject, not the subject and not the
+  document. Deleting an item of a `getObjects` result removes nothing: that result is a
+  clone.
+- **Only the owner writes.** Holding a document's read key never grants a write -
+  `insertObject` and the ORM's `graph_orm_update` are both refused otherwise, before the
+  write is attempted.
 - **Writes target one document**, never "the union": a SPARQL update must name one
   document's graph (`resolve_target_for_sparql(update=true)` returns `InvalidTarget`
   for the union, `engine/verifier/src/request_processor.rs:275`).