fix!: Schema et DeepSignalSet quittent la surface publiee, sans signature pour les porter

La regle qui avait deja retire ReadCap et InboxScope (un type n'est publie que si
une signature publiee l'utilise) rattrape une seconde recurrence : les reexports
`Schema` (@ng-org/shex-orm) et `DeepSignalSet` (@ng-org/alien-deepsignals) n'etaient
utilises par aucune signature publiee. DeepSignalSet n'apparaissait que dans la
prose decrivant l'enveloppe de useShape, jamais comme un type reel dans le paquet ;
Schema n'apparaissait nulle part ailleurs que dans ce reexport.

Contrairement a ReadCap/InboxScope, aucun des deux n'a d'usage interne ou ils
resteraient DEFINIS : ils disparaissent, sans etre deplaces.

Bump majeur vers 1.0.0-dev.12 (symbole publie retire), entree de version dans le
contrat concept et mise a jour de docs/api-contract.md (bloc de code, section 14,
annexe d'inventaire).
This commit is contained in:
Sylvain Duchesne
2026-09-24 21:10:32 +02:00
parent 7da4a0ef29
commit ae44e13859
5 changed files with 20 additions and 13 deletions
+1
View File
@@ -11,3 +11,4 @@
- TOUCHED examples/notebook/app.ts @2026-09-21 (session f93872b5-293a-4916-a353-181409a96d42) - 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 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 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)
@@ -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). - **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`. - **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. `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.
+5 -5
View File
@@ -201,8 +201,7 @@ export function useShape<T extends BaseType>(
conf: RdfOrmConfig<T> | string | undefined, conf: RdfOrmConfig<T> | string | undefined,
): ShapeResult; // { data, promise, subscription, isLoading, nextPage?, previousPage? } ): ShapeResult; // { data, promise, subscription, isLoading, nextPage?, previousPage? }
// type re-exports, index.ts:48-49 // type re-exports, index.ts:48-49
export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm"; export type { ShapeType, BaseType } from "@ng-org/shex-orm";
export type { DeepSignalSet } from "@ng-org/alien-deepsignals";
``` ```
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. 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<void>;
`@ng-eventually/polyfill` re-exports, type-only (erased at build, `src/index.ts`): `@ng-eventually/polyfill` re-exports, type-only (erased at build, `src/index.ts`):
```ts ```ts
export type { ShapeType, BaseType, Schema } from "@ng-org/shex-orm"; export type { ShapeType, BaseType } from "@ng-org/shex-orm";
export type { DeepSignalSet } from "@ng-org/alien-deepsignals";
export type { Scope } from "@ng-org/orm"; export type { Scope } from "@ng-org/orm";
export type { RdfOrmConfig } from "@ng-org/orm/all"; export type { RdfOrmConfig } from "@ng-org/orm/all";
export type { NG } from "@ng-org/web"; 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. `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 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: 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) ### `@ng-eventually/polyfill` — `src/index.ts` (the only entry since 2026-08-07)
```text ```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 docs: docCreate, sparqlQuery, sparqlUpdate
inbox: Deposit, PostOptions, post, postToDocument, processInbox, read, readForDocument, readSynced, readSyncedForDocument, share, watch inbox: Deposit, PostOptions, post, postToDocument, processInbox, read, readForDocument, readSynced, readSyncedForDocument, share, watch
storeRegistry: createEntityDoc, openDocumentInbox, privateStore, protectedStore, publicStore storeRegistry: createEntityDoc, openDocumentInbox, privateStore, protectedStore, publicStore
+1 -1
View File
@@ -1,6 +1,6 @@
{ {
"name": "@ng-eventually/polyfill", "name": "@ng-eventually/polyfill",
"version": "1.0.0-dev.11", "version": "1.0.0-dev.12",
"type": "module", "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.", "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", "main": "./src/index.ts",
+8 -4
View File
@@ -84,6 +84,13 @@
// value it has no call to obtain — and for `ReadCap`, the one value the model says a // 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 // 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 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: // Each one, and the signature that earns it its place:
// Nuri every reference the surface RETURNS // Nuri every reference the surface RETURNS
// NuriLike every reference the surface ACCEPTS // 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). // 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 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 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 } from "@ng-org/shex-orm";
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";
// The scope `useShapeQuery` takes, re-exported from the SDK rather than restated here: // 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`, // restating it is how a type drifts, and the two axes it filters on (`graphs`,
// `subjects`) are upstream's to change. // `subjects`) are upstream's to change.