Sylvain Duchesne
1957a8fe0c
Le régime des contrats est devenu bidirectionnel : chaque partie rédige sa position dans son dépôt et tire celle de l'autre. Le fournisseur écrit son engagement, chaque consommateur écrit sa déclaration — ce qu'il appelle vraiment, sous quelles contraintes, et avec quelles frictions. Ce dernier point change nos usages : la section Frictions est le chemin par lequel un consommateur expose un problème, le canal hors-bande ne portant que le signal. Les huit points que Festipod nous a remontés auraient dû arriver par là, et notre réponse appartient à l'engagement plutôt qu'à un échange qui s'évapore. Trois interfaces existaient, une seule était documentée. Elles ont maintenant leur dossier et leurs deux voix : la surface du polyfill, ng-e2e-helpers, et la couche d'indexation. On a écrit les engagements dont nous sommes l'auteur et les déclarations des consommateurs qui sont à nous — délibérément AUCUN usage_festipod : ce n'est pas notre dépôt, et décider à leur place ce qu'ils consomment viderait le mécanisme de son sens. Et la Change policy s'inverse. Elle disait « ce paquet n'offre pas de stabilité sémantique ». Refuser un schéma ne ralentit pas le mouvement — ça retire au consommateur le seul outil pour le gérer, alors qu'on faisait déjà le travail d'une publication versionnée sans lui en donner l'étiquette. Semver, donc, et les majeurs sont le cas NORMAL : une surface qui converge vers une cible qu'elle n'atteint pas encore casse souvent, et c'est le signal vrai. Le texte dit les déclencheurs plutôt que le nom du schéma — retirer un symbole publié ou resserrer un appel est un majeur, ajouter est un mineur. Version pleine sur main, pré-version sur une branche : Festipod peut épingler aujourd'hui sans qu'on lui promette du stable, et sans qu'on ait à lui retirer son adresse à la fusion. Au passage, la signature publiée de watchShape était fausse — elle annonçait un argument unique là où l'appel en prend deux. Rapporté par Festipod, confirmé indépendamment.
39 lines
2.4 KiB
Markdown
39 lines
2.4 KiB
Markdown
---
|
|
type: overview
|
|
summary: What an application may rely on from @ng-eventually/polyfill, and what it will have to delete
|
|
triggers:
|
|
keywords: [polyfill, sdk, surface, contract, publish, published, entry, export, migration, unlearn, consumer, app-facing]
|
|
paths:
|
|
- "packages/polyfill/src/index.ts"
|
|
- "packages/polyfill/src/surface/**"
|
|
- "packages/polyfill/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_polyfill-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 `polyfill-surface`; consuming applications live in other repos, pull the engagement, and declare back what they actually consume — one `usage_<consumer>.md` beside the contract, in the interface folder. 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
|
|
|
|
- `polyfill-surface/contract_polyfill-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.
|