ng-eventually/.project/concepts/app-contract/_overview.md

type, summary, triggers, vocabulary

type	summary	triggers	vocabulary
overview	What an application may rely on from @ng-eventually/polyfill, and what it will have to delete	keywords paths polyfill sdk surface contract publish published entry export migration unlearn consumer app-facing inbox deposit packages/polyfill/src/index.ts packages/polyfill/src/surface/** packages/polyfill/README.md examples/notebook/** docs/api-contract.md	term gloss not see reference a NURI that names a document and grants nothing — what an application circulates link lien share-link contract_polyfill-surface term gloss not ReadCap upstream's word for what opens a document — a reference carrying its secret token credential permission term gloss not see polyfill-era a published symbol with no counterpart in the target SDK, deleted at migration transitional shim-only 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.
• 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.