Reconnexion/ng-eventually
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: le paquet s'appelle polyfill, « SDK » désigne celui de NextGraph

Browse Source 
Le nom @ng-eventually/sdk entrait en collision avec le SDK de NextGraph, dont
ce paquet est justement un polyfill. Impossible d'écrire « le SDK » sans lever
l'ambiguïté à chaque phrase — et le contrat publié, lu par une application,
était le pire endroit pour laisser traîner ça.

packages/sdk → packages/polyfill, @ng-eventually/sdk → @ng-eventually/polyfill,
contract_sdk-surface → contract_polyfill-surface, e2e/sdk-entry.ts →
e2e/polyfill-entry.ts, docs/sdk-reference.md → docs/polyfill-reference.md.

Les occurrences de « SDK » qui désignent celui de NextGraph restent intactes,
y compris les chemins dans nextgraph-rs (sdk/js/orm, sdk/js/web). Le tri s'est
fait occurrence par occurrence, pas par substitution.

Le contrat énonce désormais son identité en une phrase : « This package is a
polyfill of NextGraph's SDK. »
This commit is contained in:
Sylvain Duchesne
2026-08-10 17:14:25 +02:00
parent 49b046268e
commit 737729c9ce
88 changed files with 122 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api-contract.md
+17 -17
View File
@@ -1,10 +1,10 @@
# API contract — what `@ng-eventually/sdk` exposes today, and what the future SDK should expose per subject
# API contract — what `@ng-eventually/polyfill` exposes today, and what the future SDK should expose per subject
> **Updated 2026-08-03, after the source layout was reorganised by migration fate** (`docs/source-layout-by-fate.md`). Paths, and three names, changed under this document: `readModel` became the directly-exported `readUnion`; `accounts` / `AccountRecord` / `AccountStorage` became `virtualUsers` / `VirtualUserRecord` / `VirtualUserStorage` (module `shared-wallet/virtual-users.ts`); `store-registry-api.ts` became `surface/placement.ts`. Two modules were created and are covered here: `emulated-verifier/branch-registers.ts` (the four durable registers, split out of the shim) and `shared-wallet/bootstrap.ts` (the injection store, split out of the `/polyfill` entry). The subject-by-subject rulings below are unaffected — what moved is where the code lives, not what it promises.
**Scope: the APP-FACING contract only.** Everything reachable from the two published entry points, and nothing else. The library's internal modules — the shim machinery, the read paths, the boundary guards — are held to the same standard (as close as possible to what NextGraph does or plans) but have their own document, `docs/internal-contract.md`: a consumer never reads that one, a maintainer does. This split was made on 2026-08-03, together with the export change described in § 15.
**Scope.** The real exported surface of `@ng-eventually/sdk` (verified against the `export` statements in `packages/sdk/src/index.ts` and `packages/sdk/src/polyfill.ts` — `package.json` maps exactly two entry points, `.` and `./polyfill`), and, for each subject, the target signature the future NextGraph JS SDK is expected to expose. Written 2026-08-03, verified against the `nextgraph-rs` clone (HEAD `213338f6`, 2026-05-16) and the installed `@ng-org/web@0.1.2-alpha.13` type declarations (`node_modules/.bun/@ng-org+web@0.1.2-alpha.13/node_modules/@ng-org/web/dist/index.d.ts`, hereafter `index.d.ts`).
**Scope.** The real exported surface of `@ng-eventually/polyfill` (verified against the `export` statements in `packages/polyfill/src/index.ts` and `packages/polyfill/src/polyfill.ts` — `package.json` maps exactly two entry points, `.` and `./polyfill`), and, for each subject, the target signature the future NextGraph JS SDK is expected to expose. Written 2026-08-03, verified against the `nextgraph-rs` clone (HEAD `213338f6`, 2026-05-16) and the installed `@ng-org/web@0.1.2-alpha.13` type declarations (`node_modules/.bun/@ng-org+web@0.1.2-alpha.13/node_modules/@ng-org/web/dist/index.d.ts`, hereafter `index.d.ts`).
**How to read the epistemic labels.** Every target-side claim carries one of:
@@ -19,7 +19,7 @@ Per the design principle (`README.md` § *Design principle*): an absent implemen
## 1. Bootstrap and configuration
### Today — `@ng-eventually/sdk`: **one call**
### Today — `@ng-eventually/polyfill`: **one call**
```ts
// shared-wallet/bootstrap.ts
@@ -57,7 +57,7 @@ So an application's whole bootstrap is `configure({ … })` plus `await ensureId
## 2. Lifecycle
### Today — `@ng-eventually/sdk`
### Today — `@ng-eventually/polyfill`
```ts
// lifecycle.ts:11 — forwards to the real @ng-org/web init injected at configure()
@@ -94,7 +94,7 @@ Divergence: none in behaviour (pure forwarding), but the wrapper erases the para
## 2bis. The access gate — `ensureIdentity`
### Today — `@ng-eventually/sdk`
### Today — `@ng-eventually/polyfill`
```ts
export async function ensureIdentity(): Promise<PrincipalId>; // shared-wallet/access-gate.ts
@@ -123,7 +123,7 @@ Why it lives here and not in the consumer application: the first consumer had ~3
## 3. The `ng` object
### Today — `@ng-eventually/sdk`
### Today — `@ng-eventually/polyfill`
```ts
// index.ts:55
@@ -147,7 +147,7 @@ The two overrides:
## 4. Reactive typed reads — `useShape`
### Today — `@ng-eventually/sdk`
### Today — `@ng-eventually/polyfill`
```ts
// use-shape.ts:12
@@ -185,7 +185,7 @@ Divergence to note: the wrapper types everything `unknown`, losing the generic `
## 5. Reactive typed reads with load state — `watchShape`
### Today — `@ng-eventually/sdk`
### Today — `@ng-eventually/polyfill`
```ts
// watch-shape.ts:73
@@ -226,7 +226,7 @@ So the constraint on the bet: the target can already answer "synced?" (`readyPro
## 6. One-shot listing — the read-model
### Today — `@ng-eventually/sdk`
### Today — `@ng-eventually/polyfill`
```ts
// read-model.ts:60
@@ -264,7 +264,7 @@ The anchored-read mechanics are level-1 VERIFIED: an anchor restricts the query
## 7. Raw document / SPARQL primitives — `docs.*`
### Today — `@ng-eventually/sdk` (namespace `docs`)
### Today — `@ng-eventually/polyfill` (namespace `docs`)
```ts
// docs.ts:46
@@ -324,7 +324,7 @@ So the target's direction for scope placement is **already visible in the source
## 8. Per-document subscription — `subscribeDoc`
### Today — `@ng-eventually/sdk`
### Today — `@ng-eventually/polyfill`
```ts
// subscribe.ts:47,60,79
@@ -362,7 +362,7 @@ declare function doc_subscribe(repo_o: string, session_id: any, callback: Functi
## 9. Inbox — deposits, and cap delivery
### Today — `@ng-eventually/sdk` (namespace `inbox`)
### Today — `@ng-eventually/polyfill` (namespace `inbox`)
```ts
export interface Deposit {
@@ -417,7 +417,7 @@ Consequences per function:
### Today
```ts
// @ng-eventually/sdk — model/types.ts. The published cap surface is now ONE type.
// @ng-eventually/polyfill — model/types.ts. The published cap surface is now ONE type.
export type Nuri = `did:ng:${string}`;
export type NuriLike = Nuri | string;
@@ -504,7 +504,7 @@ The escaping helpers were published until the surface was narrowed. Their remova
## 12. Scope resolution, per-entity documents, and the store registry
### Today — `@ng-eventually/sdk` (namespace `storeRegistry`) — plus `Scope` from `types.ts`
### Today — `@ng-eventually/polyfill` (namespace `storeRegistry`) — plus `Scope` from `types.ts`
> **Narrowed twice.** 2026-08-03 the entry stopped re-exporting the whole `store-registry` module and kept an app-facing slice (`src/surface/placement.ts`). 2026-08-05 that slice lost its two inbox-ADDRESS functions as well: an application deposits with `inbox.postToDocument(doc, …)` and shares with `inbox.share(doc, toUser)` — always naming a document or a person, never an address, because upstream an address is resolved from a profile and never handled by a caller. **Five functions remain published**, listed first below; everything after them is kept for the record and is covered by `docs/internal-contract.md`.
@@ -599,7 +599,7 @@ declare function user_disconnect(user_id: string): Promise<void>;
## 14. Type re-exports
`@ng-eventually/sdk` re-exports, type-only (erased at build, `src/index.ts`):
`@ng-eventually/polyfill` re-exports, type-only (erased at build, `src/index.ts`):
```ts
export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm";
@@ -658,9 +658,9 @@ Exported, but not SDK surface. Coding against these builds knowledge that migrat
## Appendix — full export inventory (for diffing)
*Generated from the `export` statements, and pinned by `packages/sdk/test/vocabulary.test.ts` — if this list and the code disagree, that test fails. It went stale once, still listing `storeRegistry`'s shim internals after the entry had been narrowed, which is what a hand-maintained inventory does.*
*Generated from the `export` statements, and pinned by `packages/polyfill/test/vocabulary.test.ts` — if this list and the code disagree, that test fails. It went stale once, still listing `storeRegistry`'s shim internals after the entry had been narrowed, which is what a hand-maintained inventory does.*
### `@ng-eventually/sdk` — `src/index.ts` (the only entry since 2026-08-07)
### `@ng-eventually/polyfill` — `src/index.ts` (the only entry since 2026-08-07)
```text
direct: BaseType, DeepSignalSet, DocChange, DocChangeType, EventuallyConfig, NG, NgLike, Nuri, NuriLike, PrincipalId, RegistrySession, Schema, Scope, ShapeObservable, ShapeQuery, ShapeType, SharedWalletConfig, UnionSubject, Unsubscribe, UseShapeLike, configure, docChangeType, ensureIdentity, init, initNg, ng, readUnion, subscribeDoc, subscribeDocs, useShape, watchShape