Sylvain Duchesne
b0eec7b4dc
Majeur : trois appels existants se resserrent. `useShapeQuery` publie `isError` pour un document NOMME qu'il ne peut pas lire, la ou il rendait `isSuccess` avec `data: []` - la seule image que cette surface reserve a « ce scope ne contient rien ». `inbox.postToDocument`, `readForDocument` et `readSyncedForDocument` rejettent la ou elles annoncaient « pas d'inbox ». Rien de ce qui etait deja une reponse ne bouge : un document vide, `graphs: []`, un document sans inbox, un document public qui n'expose aucune cle. Deux non-garanties corrigees parce que le changement les rend fausses : « aucune des deux lectures par forme ne va chercher la cle d'un store public » ne vaut plus que pour `useShape` et pour `did:ng:i`, et le pending eternel d'un demarrage refuse se referme sur le cas nomme. Nouveau `knowledge_what-a-failed-read-answers-upstream` : ce que la cible repond pour un document injoignable, non synchronise ou vide, et les deux collisions que l'appelant ne peut pas demeler - « n'existe pas » contre « pas connu de moi » d'un cote, « non synchronise » contre « vraiment vide » de l'autre. C'est le fait durable qui justifie la direction prise, et il vaut quel que soit le remede. `docs/internal-contract.md`, section open-repo seulement : numeros de ligne, `ensurePhysicalRepoOpen` qui n'a jamais ete un export de ce module, `ensureReposOpen` supprime, `openRepoUnguarded` absent, et le second parametre de `ensureRepoOpen`. Le reste du document porte une derive du meme age, laissee.
54 lines
4.1 KiB
Markdown
54 lines
4.1 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, inbox, deposit, IRI, urn, namespace, vocabulary, ontology, predicate, orm, useShape, getObjects, insertObject, OrmSubscription, ngSession]
|
|
paths:
|
|
- "packages/polyfill/src/index.ts"
|
|
- "packages/polyfill/src/surface/**"
|
|
- "packages/polyfill/src/emulated-verifier/machinery.ts"
|
|
- "packages/polyfill/src/emulated-verifier/index-deposit.ts"
|
|
- "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: shape read
|
|
gloss: a read whose selector is a ShEx shape, i.e. which predicates an object carries, never a list of documents
|
|
not: [typed read, shape-based read, lecture par forme]
|
|
see: knowledge_what-a-read-scope-is-upstream
|
|
- term: document read
|
|
gloss: a read selected by naming documents - upstream anchors ONE, so naming several is this package's own composition
|
|
not: [bulk read, union read, lecture par document]
|
|
- 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 `.project/rules/nextgraph/no-divergence-from-nextgraph.md`.
|
|
|
|
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.
|
|
- `.project/rules/nextgraph/no-divergence-from-nextgraph.md` — 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.
|
|
- `knowledge_what-an-iri-says-upstream` — the same two fates for a written *triple*: NextGraph's own vocabulary, ours, and which of our IRIs must outlive the migration.
|
|
- `knowledge_what-a-read-scope-is-upstream` — what the target offers for reading many objects at once, and the one question it cannot express.
|
|
- `knowledge_what-a-failed-read-answers-upstream` - the other half of the same question: what an unreachable, an unsynced and an empty document each answer, and which of them a caller can tell apart.
|
|
- `knowledge_what-the-orm-writes-and-deletes-upstream` — the writing half: removal is a set mutation wired end to end, and an ORM write never passes through `sparql_update`.
|
|
- `knowledge_what-an-inbox-is-upstream` — what the target actually offers around inboxes, and where a choice of ours begins.
|
|
- `knowledge_who-processes-an-inbox` — the division of labour along a deposit's path: what this package applies, what it merely delivers, and what a layer above owes itself.
|