Sylvain Duchesne
33b96fdc8d
La feuille testait ce que l'APPELANT apprendrait. Le propriétaire du projet a énoncé la règle plus large : rester au plus près de NextGraph, et n'admettre aucune implémentation qui en diverge — que l'appelant s'en aperçoive ou non. L'ordre des deux questions est ce qui a manqué. Sur la fusion de `readUnion`, posée en premier, « l'appelant devra-t-il désapprendre ? » ne tranchait pas : « une entité par document » est une bonne pratique par ailleurs, alors que désapprendrait-il au juste ? Le raisonnement a piétiné des heures là-dessus. Posée en premier, « la cible fait-elle ça ? » a demandé un regard : le niveau 1 rend les sujets réels, et l'ORM du niveau 3 porte `@id` ET `@graph` sur chaque objet en fabriquant le premier quand on l'omet. Divergence, fin. « Devra-t-il désapprendre ? » reste, mais mesure la gravité d'une divergence inévitable — jamais son autorisation. Et un tell est ajouté, celui qui a produit ce défaut : une recommandation que le code impose au lieu de la guider, en rendant l'autre disposition invisible.
39 lines
2.2 KiB
Markdown
39 lines
2.2 KiB
Markdown
---
|
|
type: overview
|
|
summary: What an application may rely on from @ng-eventually/sdk, and what it will have to delete
|
|
triggers:
|
|
keywords: [polyfill, sdk, surface, contract, publish, published, entry, export, migration, unlearn, consumer, app-facing]
|
|
paths:
|
|
- "packages/sdk/src/index.ts"
|
|
- "packages/sdk/src/surface/**"
|
|
- "packages/sdk/README.md"
|
|
- "examples/notebook/**"
|
|
- "docs/api-contract.md"
|
|
vocabulary:
|
|
- term: reference
|
|
gloss: a NURI that names a document and grants nothing — what an application circulates
|
|
not: [link, lien, share-link]
|
|
see: contract_sdk-surface
|
|
- term: ReadCap
|
|
gloss: upstream's word for what opens a document — a reference carrying its secret
|
|
not: [token, credential, permission]
|
|
- term: polyfill-era
|
|
gloss: a published symbol with no counterpart in the target SDK, deleted at migration
|
|
not: [transitional, shim-only]
|
|
see: knowledge_what-an-app-deletes-at-migration
|
|
---
|
|
|
|
# app-contract — the boundary between this library and the applications that use it
|
|
|
|
This library exists so an application can be **written today against the NextGraph that does not ship yet**, and keep its code when it does. Everything under this concept governs that boundary: what the package publishes, what a caller may rely on, what it must not, and what disappears at migration.
|
|
|
|
The distinguishing question, asked at every choice — published signature as much as internal mechanism: **does the target do this?** If it does it differently, we do it their way, whatever that costs. *Would a caller have to unlearn it?* comes second, and measures how bad a divergence is — never whether one is allowed. See `rule_no-divergence-from-nextgraph`.
|
|
|
|
This repo is the **provider** of `contract_sdk-surface`; consuming applications live in other repos and pull it. The per-symbol ruling, with an epistemic label on every target-side claim, stays here in `docs/api-contract.md` — that is maintainer material, not the engagement.
|
|
|
|
## Read first
|
|
|
|
- `contract_sdk-surface` — the engagement itself, written from the caller's point of view.
|
|
- `rule_no-divergence-from-nextgraph` — the test that decides what may be built at all.
|
|
- `knowledge_what-an-app-deletes-at-migration` — the two fates a published symbol can have.
|