Sylvain Duchesne
d3a2c33b92
Règle posée par l'utilisateur : la seule raison d'être du polyfill est de combler un retard d'implémentation NextGraph ou un bug. Aucune fonctionnalité additionnelle propre (pas de feature, d'observabilité, d'API de confort qui ne soit pas « NextGraph le fera nativement plus tard »). Corollaire : une compensation dont le gap n'est PAS exhibé sur le broker cible est du poids mort, pas du code défensif — à retirer. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
49 lines
2.6 KiB
Markdown
49 lines
2.6 KiB
Markdown
# @ng-eventually/client
|
|
|
|
Two entry points — the data-plane is SDK-identical, the polyfill bootstrap is
|
|
separate:
|
|
|
|
| Import | Surface |
|
|
|---|---|
|
|
| `@ng-eventually/client` | The same signature as the SDK — `ng`, `useShape`, `inbox` (+ types). A drop-in for `@ng-org/web` / `@ng-org/orm`; as NextGraph matures it resolves to the real SDK (build alias removed) with no code change. |
|
|
| `@ng-eventually/client/polyfill` | The only non-SDK surface — `configure`, `setCurrentUser`, and capability helpers (`getCaps`, `grantRead`, `canRead`/`canWrite`). It falls away as NextGraph matures. |
|
|
|
|
```ts
|
|
// bootstrap (the only non-SDK call) — inject the real SDK
|
|
import { configure } from "@ng-eventually/client/polyfill";
|
|
configure({ ng: realNg, useShape: realUseShape, sharedWallet, currentUser });
|
|
|
|
// from here on, a pure SDK surface:
|
|
import { ng, useShape, inbox } from "@ng-eventually/client";
|
|
await ng.doc_create(/* … */);
|
|
const set = useShape(MyShape, scope); // filtered to what the identity may read
|
|
await inbox.post(targetInbox, ref); // deposit (anticipated SDK API)
|
|
```
|
|
|
|
## Principle — the polyfill compensates, it never extends
|
|
|
|
**The polyfill's ONLY reason to exist is to bridge a NextGraph implementation gap
|
|
or a bug.** Every non-SDK surface must map to a capability NextGraph will provide
|
|
natively, and must fall away at that point. The polyfill MUST NOT add functionality
|
|
of its own — no bespoke features, no observability/tooling, no convenience API that
|
|
isn't strictly "NextGraph will do this natively later." The test for any proposed
|
|
addition: *does it compensate a real, exhibited NextGraph gap or bug?* If not, it
|
|
does not belong here — build it in the consumer application, not in the polyfill.
|
|
Corollary: a compensation whose gap is not actually exhibited on the target broker
|
|
is dead weight, not defensive code — it should be removed, not kept "just in case."
|
|
|
|
What the polyfill adds on top of the real SDK (each emulated for now, native as
|
|
NextGraph matures):
|
|
- Shared-wallet identity (one wallet for everyone; the current identity id is
|
|
relayed to the SDK).
|
|
- Capability enforcement — a read filter + write guard over emulated grants
|
|
attached to documents; the app declares a document's read policy and issues
|
|
directed read grants.
|
|
- Anticipated methods (inbox `post`, capability ops) with their future-SDK shapes,
|
|
emulated for now.
|
|
|
|
Generic: no application domain. The consumer application injects its shapes and
|
|
performs the acts of granting access. The relationship concept ("who is connected
|
|
to whom") is the consumer application's own — the client exposes only directed
|
|
per-document read grants.
|