diff --git a/.project/concepts/app-contract/_debt.md b/.project/concepts/app-contract/_debt.md index 9beb220..2514d19 100644 --- a/.project/concepts/app-contract/_debt.md +++ b/.project/concepts/app-contract/_debt.md @@ -11,3 +11,4 @@ - TOUCHED examples/notebook/app.ts @2026-09-21 (session f93872b5-293a-4916-a353-181409a96d42) - TOUCHED packages/polyfill/src/surface/subscribe.ts @2026-09-24 (session f93872b5-293a-4916-a353-181409a96d42) - TOUCHED examples/notebook/package.json @2026-09-24 (session f93872b5-293a-4916-a353-181409a96d42) +- TOUCHED docs/api-contract.md @2026-09-24 (session f93872b5-293a-4916-a353-181409a96d42) diff --git a/.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md b/.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md index f5c57f3..45fa9dd 100644 --- a/.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md +++ b/.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md @@ -280,11 +280,13 @@ What each level means here, in this package's own terms: - **minor** — a symbol is added and nothing existing moves (`inbox.readSyncedForDocument` arrived this way). - **patch** — a fix that changes neither the published surface nor anything above under `## Guarantees`. -**A tag says where it comes from.** A release cut on `main` carries a **full version** (`1.0.0`), and the three rules above govern what changes between two full versions. Work still on a branch carries a **pre-release** of the version it is heading for (`1.0.0-dev.11`), which sorts *below* that version by construction - so you can pin what exists today while the tag itself tells you the surface has not been released and may still move before it is. Between two pre-releases of the same version nothing is promised: re-pull and read this leaf again. When the branch lands, the full version appears alongside; the pre-release keeps resolving, so no reference you pinned is ever withdrawn from under you. +**A tag says where it comes from.** A release cut on `main` carries a **full version** (`1.0.0`), and the three rules above govern what changes between two full versions. Work still on a branch carries a **pre-release** of the version it is heading for (`1.0.0-dev.12`), which sorts *below* that version by construction - so you can pin what exists today while the tag itself tells you the surface has not been released and may still move before it is. Between two pre-releases of the same version nothing is promised: re-pull and read this leaf again. When the branch lands, the full version appears alongside; the pre-release keeps resolving, so no reference you pinned is ever withdrawn from under you. -**Tags carry the package name**, because this repository publishes more than one engagement and their versions move independently: `polyfill/v1.0.0-dev.11` is this package, `ng-e2e-helpers/v...` is the other one. A bare `v...` tag would say nothing about which surface it froze the day the two diverge - which is the day one of them takes a major and the other does not. +**Tags carry the package name**, because this repository publishes more than one engagement and their versions move independently: `polyfill/v1.0.0-dev.12` is this package, `ng-e2e-helpers/v...` is the other one. A bare `v...` tag would say nothing about which surface it froze the day the two diverge - which is the day one of them takes a major and the other does not. -`1.0.0` is a baseline, not a claim of maturity: it is the number that makes your pin mean something. Nothing was released before it, so none of the changes named above is a bump from anything - but the next release very likely is a major. What exists today is `1.0.0-dev.11`, on a branch: pin that string exactly, and anchor your `usage_` leaf's `against:` on it - `against: @ng-eventually/polyfill@1.0.0-dev.11`, the string you pinned, never the version it is heading for. +`1.0.0` is a baseline, not a claim of maturity: it is the number that makes your pin mean something. Nothing was released before it, so none of the changes named above is a bump from anything - but the next release very likely is a major. What exists today is `1.0.0-dev.12`, on a branch: pin that string exactly, and anchor your `usage_` leaf's `against:` on it - `against: @ng-eventually/polyfill@1.0.0-dev.12`, the string you pinned, never the version it is heading for. + +`1.0.0-dev.12` is a **major**, and it is one removal: **`Schema` (`@ng-org/shex-orm`) and `DeepSignalSet` (`@ng-org/alien-deepsignals`) are gone from the entry, and nothing replaces them.** Both were re-exported type-only under `## Surface`'s own rule - a type is published only when a published signature uses it - and neither was: `DeepSignalSet` is named only in prose describing what `useShape`'s result carries, never as an actual type anywhere in this package, and `Schema` was named nowhere at all beyond the re-export itself. The same rule already removed `ReadCap` and `InboxScope` from this list; this is that rule catching a second, later recurrence. If your code names either type, it stays DEFINED nowhere in this package to fall back on - name the SDK package directly (`@ng-org/shex-orm`, `@ng-org/alien-deepsignals`) if you need it. `1.0.0-dev.11` is a **major**, and all of it is one rule: **`useShape` hands back NextGraph's own RESULT OBJECT, filtered - and the filter no longer decides what to hand on by what a member is CALLED.** Nothing is added, renamed or removed from the entry. diff --git a/docs/api-contract.md b/docs/api-contract.md index c5a61bc..0e2b231 100644 --- a/docs/api-contract.md +++ b/docs/api-contract.md @@ -201,8 +201,7 @@ export function useShape( conf: RdfOrmConfig | string | undefined, ): ShapeResult; // { data, promise, subscription, isLoading, nextPage?, previousPage? } // type re-exports, index.ts:48-49 -export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm"; -export type { DeepSignalSet } from "@ng-org/alien-deepsignals"; +export type { ShapeType, BaseType } from "@ng-org/shex-orm"; ``` Behaviour: forwards to the injected real hook; once any emulated cap exists (`caps.isEnforcing()`), the RESULT OBJECT is wrapped in a read-filtered view. `data` and `promise` yield only items whose document cap the current holder has, `subscription` is refused (it is the ORM's own handle, which this surface does not publish), `isLoading` and the two page commands pass through, and any other member is refused unless what is behind it is a plain scalar - the rule is the value's type, so a member a later release adds is decided before anyone has seen it. @@ -762,8 +761,7 @@ declare function user_disconnect(user_id: string): Promise; `@ng-eventually/polyfill` re-exports, type-only (erased at build, `src/index.ts`): ```ts -export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm"; -export type { DeepSignalSet } from "@ng-org/alien-deepsignals"; +export type { ShapeType, BaseType } from "@ng-org/shex-orm"; export type { Scope } from "@ng-org/orm"; export type { RdfOrmConfig } from "@ng-org/orm/all"; export type { NG } from "@ng-org/web"; @@ -775,6 +773,8 @@ A type is erased at build, so re-exporting one adds no runtime `@ng-org` import `RdfOrmConfig` comes from the SDK's `/all` subpath rather than its main entry, and that is upstream's packaging rather than a choice here: the config type `getObjects` declares is not exported beside the function that takes it (§ 6bis). Restating it locally is how a type drifts, so it is re-exported from where the SDK puts it. +**`Schema` (`@ng-org/shex-orm`) and `DeepSignalSet` (`@ng-org/alien-deepsignals`) were re-exported here until `1.0.0-dev.12` (2026-09-24), and are UNPUBLISHED now, for the same rule this section states: a type is published only when a published signature uses it. Neither was. `DeepSignalSet` is named only in prose describing what `useShape`'s result envelope carries (§ 4) - never as an actual type anywhere in this package - and `Schema` was named nowhere at all beyond this re-export. This is a MAJOR (a published symbol removed); see the concept contract's `## Change policy` (`.project/concepts/app-contract/polyfill-surface/contract_polyfill-surface.md`) and the appendix below.** + ### The library's own model types — published by NAME since 2026-08-10 The entry used to say `export * from "./model/types"`, a blanket re-export publishing eight types in one gesture. It now names them, under one rule: @@ -832,7 +832,7 @@ Exported, but not SDK surface. Coding against these builds knowledge that migrat ### `@ng-eventually/polyfill` — `src/index.ts` (the only entry since 2026-08-07) ```text -direct: BaseType, DeepSignalSet, DocChange, DocChangeType, EventuallyConfig, GetObjectsLike, InsertObjectLike, NG, NgLike, Nuri, NuriLike, OrmSubscriptionLike, PrincipalId, RdfOrmConfig, Schema, Scope, ShapeObservable, ShapeQuery, ShapeType, SharedWalletConfig, Unsubscribe, UseShapeLike, configure, docChangeType, ensureIdentity, getObjects, init, initNg, insertObject, ng, subscribeDoc, subscribeDocs, useShape, useShapeQuery +direct: BaseType, DocChange, DocChangeType, EventuallyConfig, GetObjectsLike, InsertObjectLike, NG, NgLike, Nuri, NuriLike, OrmSubscriptionLike, PrincipalId, RdfOrmConfig, Scope, ShapeObservable, ShapeQuery, ShapeType, SharedWalletConfig, Unsubscribe, UseShapeLike, configure, docChangeType, ensureIdentity, getObjects, init, initNg, insertObject, ng, subscribeDoc, subscribeDocs, useShape, useShapeQuery docs: docCreate, sparqlQuery, sparqlUpdate inbox: Deposit, PostOptions, post, postToDocument, processInbox, read, readForDocument, readSynced, readSyncedForDocument, share, watch storeRegistry: createEntityDoc, openDocumentInbox, privateStore, protectedStore, publicStore diff --git a/packages/polyfill/package.json b/packages/polyfill/package.json index c892f93..a4a8a29 100644 --- a/packages/polyfill/package.json +++ b/packages/polyfill/package.json @@ -1,6 +1,6 @@ { "name": "@ng-eventually/polyfill", - "version": "1.0.0-dev.11", + "version": "1.0.0-dev.12", "type": "module", "description": "Polyfill of the NextGraph JS SDK over @ng-org/web + @ng-org/orm, with emulated capabilities and inbox. Drop-in; remove at migration.", "main": "./src/index.ts", diff --git a/packages/polyfill/src/index.ts b/packages/polyfill/src/index.ts index c427f3a..a134056 100644 --- a/packages/polyfill/src/index.ts +++ b/packages/polyfill/src/index.ts @@ -84,6 +84,13 @@ // value it has no call to obtain — and for `ReadCap`, the one value the model says a // caller must never be handed on request. They stay DEFINED in `model/types.ts`, where // the library uses them; they stop being surface. `docs/api-contract.md` § 10, § 14. +// +// The same rule caught a second, later recurrence (2026-09-24): the SDK type re-exports +// below carried `Schema` (from `@ng-org/shex-orm`) and `DeepSignalSet` (from +// `@ng-org/alien-deepsignals`), neither used by a published signature — `DeepSignalSet` +// is named only in prose describing what `useShape`'s result envelope carries, never as +// an actual type anywhere in this package. Unlike `ReadCap` / `InboxScope`, neither has +// an internal use to stay DEFINED for: they are simply gone, not moved. // Each one, and the signature that earns it its place: // Nuri every reference the surface RETURNS // NuriLike every reference the surface ACCEPTS @@ -145,10 +152,7 @@ export * as storeRegistry from "./surface/placement"; // the lib (no risk of a duplicate SDK copy in the bundle). // @provenance ShapeType kind=passthrough level=3 ref=sdk/js/shex-orm/src/types.ts:ShapeType // @provenance BaseType kind=passthrough level=3 ref=sdk/js/shex-orm/src/types.ts:BaseType - the cited revision keeps `"@graph"` commented out behind a TODO; the published `@ng-org/shex-orm@0.1.2-alpha.9` declares it, and it is the published one that is re-exported here -// @provenance Schema kind=passthrough level=3 ref=sdk/js/shex-orm/src/types.ts:Schema -export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm"; -// @provenance DeepSignalSet kind=passthrough level=3 ref=sdk/js/alien-deepsignals/src/types.ts:DeepSignalSet -export type { DeepSignalSet } from "@ng-org/alien-deepsignals"; +export type { ShapeType, BaseType } from "@ng-org/shex-orm"; // The scope `useShapeQuery` takes, re-exported from the SDK rather than restated here: // restating it is how a type drifts, and the two axes it filters on (`graphs`, // `subjects`) are upstream's to change.