docs: le modèle applicatif partagé passe par une app singleton
Réécriture de « Apps & services » : la version précédente déduisait la forme cible de l'absence d'implémentation dans le moteur — exactement ce que le principe de conception du README interdit — et concluait l'inverse de ce que le développeur NextGraph énonce. Deux couches désormais séparées et étiquetées comme telles : - ce que le moteur CONTIENT (vérifié) : `AppManifestV0` avec `singleton: bool`, `access_requests`, `installs`, `dependencies` ; `init(callback, singleton, access_requests)` côté JS. Et personne ne le consomme — le module `permissions` n'est importé par aucune crate, `AppManifest` n'est construit nulle part. Du vocabulaire, pas du comportement. - ce que le modèle SERA (énoncé par le développeur, non implémenté) : une app singleton peut aussi gérer les documents par utilisateur ; les données communes prennent la forme d'un document ou d'un store partagé par tous les utilisateurs et codé en dur dans l'app ; le développeur détient les droits d'écriture et peut les déléguer, jamais à tous — les contributions arrivent par une inbox. Le commentaire du champ dit `/// cannot create Documents?`, avec le point d'interrogation. Une seconde glose publiée le contredit et rejoint ce que dit le développeur : `sdk/js/web/README.md:90,108` annote l'argument « will your app create many docs in the system, or should it be launched as a unique instance » — `singleton` porte sur la multiplicité d'instance, pas sur une interdiction de créer des documents. C'est cette lecture qu'il faut retenir. Conséquence sur l'ADR discovery : sa moitié « la voie app singleton est incertaine » est caduque et doit être re-posée, sans que cela rétablisse la découverte, qui tient sur son propre appui.
This commit is contained in:
Sylvain Duchesne
@@ -69,12 +69,7 @@ is needed), and how this lib emulates it today.
|
||||
|---|---|
|
||||
| `@ng-eventually/client` | The SDK-identical wrapper the app imports instead of `@ng-org/web` / `@ng-org/orm`. It adds the polyfills the broker/verifier will do natively (shared-wallet identity, capability enforcement, anticipated cap/inbox methods). As NextGraph matures, the app points back at the real SDK (build alias removed) and this package falls away. |
|
||||
|
||||
A global-index package is deferred. In NextGraph an identity's apps and services
|
||||
see only what it shares, so there is no multi-identity backend. A global index
|
||||
would come from a singleton app (a global document administered by the developer),
|
||||
which is not implemented and undecided; simpler paths may exist. So there is no
|
||||
second package for now — it will be introduced once the global-index mechanism is
|
||||
decided, and it will be separate from the client.
|
||||
A global-index package is deferred. Data common to all of an application's users comes from a **singleton app**: a document or store shared by all users and hardcoded in the app, write-owned by the developer and delegable — but never to all users, so user contributions reach it **through an inbox** (nothing in NextGraph is freely writable by everyone). That is the direction the NextGraph developer has named; it is **not implemented**, and several points are still open (what exactly is hardcoded, how delegation travels, who materializes the inbox). So there is no second package for now — it will be introduced once the mechanism exists, and it will be separate from the client. See [`docs/nextgraph-current-state.md`](docs/nextgraph-current-state.md) § Apps & services.
|
||||
|
||||
## Design principle
|
||||
|
||||
|
||||
@@ -11,6 +11,8 @@
|
||||
>
|
||||
> This ADR already recorded the first half of that verdict — *"a dedicated service with its own wallet sharing a freely-readable index is not a NextGraph shape"*, resting on a singleton-app path *"not implemented, uncertain"*. That reservation is now the conclusion.
|
||||
>
|
||||
> **Amended 2026-08-03 — the singleton-app half must be re-put, not cited as closed.** The NextGraph developer has since named the singleton app as *the* way an application holds data common to all its users: a document or store shared by all users, hardcoded in the app, write-owned by the developer and delegable — never delegated to all users, so user contributions arrive **through an inbox**. Still unimplemented, but no longer uncertain in direction. This does **not** reinstate discovery — the "you cannot discover, you can only follow links" verdict stands on its own footing, and count 2 above is about pooling users' data across wallets, not about an app's own data. What is void is treating "the singleton path is uncertain" as a settled argument. See [`../nextgraph-current-state.md`](../nextgraph-current-state.md) § Apps & services.
|
||||
>
|
||||
> **`discovery.ts` and its tests were removed on 2026-07-30**, along with `watchShape`'s public-scope fold and `INDEX_ACCOUNT`. See [`../briefs/2026-07-30-virtual-wallet-boundary.md`](../briefs/2026-07-30-virtual-wallet-boundary.md).
|
||||
>
|
||||
> One factual error below is worth naming so it is not carried into a future design: *"a native inbox (a primitive present on every document)"* is **false**. No document has an inbox upstream — only the public and protected STORE repos do (`engine/verifier/src/site.rs:128,149`; `doc_create` leaves `inbox: None`, `engine/repo/src/repo.rs:574`). See [`../nextgraph-current-state.md`](../nextgraph-current-state.md) § Inbox.
|
||||
|
||||
@@ -467,39 +467,37 @@ methods: `doc_subscribe`, `orm_start_graph`, `orm_start_discrete`, `file_get`,
|
||||
(`pnpm webfilebuild`). First boot is **interactive** (admin-wallet invitation
|
||||
link). Official Dockerfiles are **broken**.
|
||||
|
||||
## Apps & services: mono-user, no global data
|
||||
## Apps & services: shared app data goes through a hardcoded app store (section rewritten 2026-08-03)
|
||||
|
||||
NextGraph's app/service execution model — important because it **invalidates**
|
||||
the idea of "a service with its own wallet sharing global data".
|
||||
NextGraph's app/service execution model, and the answer to "can an application hold data common to all its users".
|
||||
|
||||
> **Provenance: NOT verified against `nextgraph-rs`.** Every other section of this file
|
||||
> cites the engine; this one cites nothing, and nothing in the local clone corresponds to
|
||||
> it — no app/service runtime, no settings-document type, no singleton notion. It arrived
|
||||
> with `bea9f51`, moved wholesale from the consumer app's repo, and its own source (an
|
||||
> exchange with the PO, the official docs, or an inference) was not recorded. The
|
||||
> conclusion below carries real weight — it is what deferred a global index in this lib —
|
||||
> so treat it as **a claim to re-confirm with the PO**, not as an engine fact. Do not
|
||||
> extend it, and do not cite it as verified.
|
||||
> **Provenance — two layers, do not mix them.** What the **engine** contains is verified below and is vocabulary only. What the **model will be** was stated by the NextGraph developer on 2026-08-03 and is **not implemented**: treat it as the target's declared direction, not as something the clone can confirm. Per [`../README.md`](../README.md)'s design principle, never infer the target's shape from the source's current state — an absent implementation says nothing about the intended one. The previous version of this section drew exactly that inference and concluded the opposite of what the developer states; it has been replaced.
|
||||
|
||||
- **Apps AND services are mono-user.** They see only **what the user makes
|
||||
available** to them. There is **no global data** natively, and no central
|
||||
service holding shared data.
|
||||
- **Local settings document.** Every app — even a singleton — and every service
|
||||
has a **settings document** the user configures it through.
|
||||
- **Multi-instance apps.** A **non-singleton** app can be **instantiated several
|
||||
times** (e.g. a text editor, once per open file).
|
||||
- **Singleton apps.** Also **mono-user**, but **bound to a particular user (the
|
||||
developer)**. A singleton app **can hold a global document**, administered by
|
||||
that user.
|
||||
**What the engine actually has — types, no behaviour (verified 2026-08-03):**
|
||||
|
||||
**Consequence for a "global document" (e.g. a discovery index):** the only path
|
||||
glimpsed is a singleton app whose global document is administered by the
|
||||
developer-user — though this is not implemented and not guaranteed (simpler
|
||||
paths may exist; to explore later). The model that does exist is this
|
||||
singleton-app one; a dedicated service with its own wallet sharing a
|
||||
freely-readable index is not a NextGraph shape (a service is mono-user, no global
|
||||
data). This is why a global-index package is deferred in this lib (see the top-level
|
||||
README).
|
||||
- `AppManifestV0` (`engine/wallet/src/permissions.rs:113`) carries `nuri`, `origin` (webapps), `singleton: bool`, `access_requests`, `installs` (Viewer / Editor / ReadService / WriteService / Model, keyed by PrimaryClass), `dependencies`, and presentation fields.
|
||||
- The JS surface exists: `init(callback, singleton, access_requests)` (`sdk/js/web/src/index.ts:51`) relays `singleton` to the wallet origin by `postMessage`. Every example passes `true`.
|
||||
- **Nothing consumes it.** The `permissions` module is declared by `engine/wallet/src/lib.rs:19` and imported by no other crate; `AppManifest` is constructed nowhere; no code reads `singleton`; the surrounding `AccessRequest` / `AccessGrant` machinery is in the same state. There is no app runtime, no app store, no global-document type.
|
||||
- The field's doc comment reads `/// cannot create Documents?` — with the question mark, in the source. It is an open design note, and the developer's statement below settles it the other way. Do not treat it as the semantics.
|
||||
- **A second, published gloss of the same flag disagrees with that doc comment, and it is the one that matches the developer's statement.** `sdk/js/web/README.md:90,108` annotates the argument as *"will your app create many docs in the system, or should it be launched as a unique instance"* — i.e. `singleton` is about **instance multiplicity**, not about being forbidden to create documents. That is consistent with "a singleton app can also manage ordinary per-user documents" below, and it is the reading to carry. Both README examples pass `true`.
|
||||
- Unrelated homonyms, so a grep does not mislead: singleton *commits* (`engine/repo/`), the broker singleton (`engine/net/src/broker.rs`), Oxigraph's `empty_singleton` (SPARQL optimiser).
|
||||
|
||||
**The declared model (NextGraph developer, 2026-08-03 — not implemented):**
|
||||
|
||||
- A singleton app can **also** manage ordinary per-user documents, i.e. cover what a non-singleton app does. When both modes are needed, declaring one app as singleton is enough — there is no need for two apps.
|
||||
- Centralized data for an application takes the form of a **document, or a store, shared by all its users and hardcoded in the app**.
|
||||
- The **app's developer holds the write rights** on the app's documents and stores, and can **delegate** them.
|
||||
- Delegation is **never to all users**. User contributions reach app-owned data **through an inbox** — this is NextGraph's general model, in which nothing is freely writable by everyone.
|
||||
|
||||
**Reading of the last point, since it decides the shape of any index:** an app-owned index is not a place users write to. It is a document they can read (its NURI being hardcoded) and **deposit into**, with an authority derived from the developer materializing the deposits — the same deposit-then-materialize shape the inbox already imposes elsewhere, moved up to the app level.
|
||||
|
||||
**Open questions to put to the developer before designing on this:**
|
||||
|
||||
- What exactly is hardcoded — the store's or document's NURI, and does that carry the read capability?
|
||||
- How is write delegation transmitted, and is it revocable?
|
||||
- Who processes the app store's inbox: an instance running with the developer's rights, a service, something else? A deposit nobody materializes is not an index.
|
||||
|
||||
**Bearing on [`decisions/discovery-model.md`](decisions/discovery-model.md):** that ADR's superseding block leans in part on the singleton-app path being "not implemented, uncertain". The path is still not implemented, but it is no longer uncertain in direction — the developer names it as *the* way to hold data common to all users. That does not reinstate discovery: the "you cannot discover, you can only follow links" verdict rests on its own footing (the PO, 2026-07-30). It does mean the *singleton-app* half of that reasoning must be re-put rather than cited as closed.
|
||||
|
||||
## Third-party wallet auto-import constraint
|
||||
|
||||
|
||||
Reference in New Issue
Block a user