refactor(api): partager nomme le document, détenir répond par oui ou non

`shareCap(cap, toUser)` faisait tenir une clé à l'appelant. En amont il n'en
tient aucune : c'est le verifier qui remplit `ContactDetails.read_cap`, et une
inbox se résout depuis un profil. Cette signature a déjà changé deux fois
aujourd'hui — `(cap, toInbox)` puis `(cap, toUser)` — et les deux laissaient à
l'app quelque chose qu'elle ne tiendra pas plus tard.

- `inbox.share(doc, toUser)` : les deux choses qu'une application a, un document
  et une personne. Ni la clé ni l'adresse n'apparaissent.
- `hasCap(doc)` remplace `capFor(doc)` et rend un BOOLÉEN. C'est la seule
  question que le modèle admette, et l'unique appelant qui utilisait la valeur
  s'en servait pour la passer à `shareCap`.

Les tests ont fait apparaître un besoin que ces retraits allaient casser :
obtenir le lien PARTAGEABLE d'un document publié, pour le faire circuler. C'est
distinct du partage dirigé et ça existe en amont — un `RepoLinkV0 { read_cap }`
est ce qu'on passe, `ContactDetails.read_cap` est la remise à quelqu'un. D'où
`linkTo(doc)`, seul endroit où une app tient légitimement une clé : on ne peut
pas faire circuler ce qu'on n'a pas le droit de toucher. La clé d'un document
protégé, elle, ne sort jamais par là — elle passe par `share`.

171 tests unitaires, e2e 42/42 en 3,5 min (synchro à froid 29s, stable contre
30s au run précédent — le wallet par batterie tient).

packages/client/src/surface/placement.ts

@@ -39,4 +39,37 @@ export {
   /** Open an inbox on a document you OWN, so others can deposit into it. */
   /** WHERE to deposit for a document — readable by any holder of it. `undefined` if none. */
 } from "../shared-wallet/account-registry";
+
+import { getCaps } from "../shared-wallet/bootstrap";
+import { toNuri } from "../model/nuri";
+import type { NuriLike, ReadCap } from "../model/types";
 export { openDocumentInbox } from "../emulated-verifier/branch-registers";
+
+/**
+ * The shareable link of a document — what you circulate so someone can open it.
+ *
+ * Distinct from {@link share}, and both are needed: a link is what TRAVELS (a message,
+ * a QR code, a page), whereas sharing hands the access to one named person through
+ * their inbox. Upstream the same split exists — a `RepoLinkV0 { read_cap }` is the
+ * thing you pass around, and `ContactDetails.read_cap` is the directed delivery.
+ *
+ * This is the one place an application legitimately holds a key, because a public
+ * document's link IS meant to be handled: you cannot circulate what you may not touch.
+ * A protected document's key never comes out this way — it goes through `share`.
+ *
+ * Typed `ReadCap`, since that is what it is — a reference with the key inside. A
+ * `ReadCap` is assignable wherever a `Nuri` is expected (a cap IS a NURI carrying the
+ * key, upstream's one `NuriV0`), so it hands straight to any call that takes a
+ * reference. Throws if you hold nothing: a link you cannot open is not a link.
+ */
+export function linkTo(doc: NuriLike): ReadCap {
+  const target = toNuri(doc, "linkTo");
+  const cap = getCaps().capFor(target);
+  if (!cap) {
+    throw new Error(
+      "[ng-eventually] linkTo: you hold no key for this document, so there is no link " +
+        `to hand out: ${JSON.stringify(target)}`,
+    );
+  }
+  return cap;
+}