feat!: useShapeQuery lit par la requete de forme du SDK

packages/polyfill/src/model/types.ts

@@ -2,6 +2,12 @@
  * Generic, NextGraph-shaped types. ZERO application domain.
  */
 
+// The SDK's own types, imported as TYPES (erased at build, so this module stays free of
+// any runtime `@ng-org` import). They describe what `configure` RECEIVES; nothing here
+// re-exports them.
+import type { Scope } from "@ng-org/orm";
+import type { BaseType, ShapeType } from "@ng-org/shex-orm";
+
 /**
  * A NextGraph URI (document / store / inbox) in its **cap-less** form — it NAMES
  * and locates, it does not grant the right to read: `did:ng:o:{doc}:v:{overlay}`.
@@ -72,6 +78,54 @@ export type NgLike = Record<string, any>;
 // @provenance UseShapeLike kind=invention level=none ref=none — same, for the injected `useShape`
 export type UseShapeLike = (...args: any[]) => any;
 
+/**
+ * The shape query in force, as `surface/use-shape-query.ts` reads it - the four members
+ * of `RdfOrmSubscription` this package touches, and not one more.
+ *
+ * NOT published: an application never holds one. It hands {@link OrmSubscriptionLike}
+ * to `configure` and reads the snapshot back; what the query itself offers is the SDK's
+ * business, and re-publishing it here would hand a caller a path around the capability
+ * filter and the shared-wallet identity boundary.
+ *
+ * `signalObject` is typed `Iterable<unknown>` rather than by the shape: upstream it is a
+ * `DeepSignalSet<T>` whose items are `DeepSignal<T>`, and narrowing it here would make
+ * the real `getOrCreate` unassignable to the injection for a difference no reader of
+ * this package can act on. The items are typed where the shape says what they are.
+ */
+// @provenance OrmSubscriptionHandle kind=aligned level=3 ref=sdk/js/orm/src/connector/GraphOrmSubscription.ts:OrmSubscription - the members this package reads: the readiness promise, the signal object, the change listeners and `close`; the published `@ng-org/orm@0.1.2-alpha.21` renames the class `RdfOrmSubscription`, which the cited revision has not yet done
+export interface OrmSubscriptionHandle {
+  /** Resolves when the initial payload has arrived, and on no other path - which is
+   *  what tells "not ready yet" from "ready and empty". Never rejects upstream today. */
+  readonly readyPromise: Promise<unknown>;
+  /** The live objects matching the shape and scope. A set (or an ordered array) that
+   *  the engine's patches keep up to date. */
+  readonly signalObject: Iterable<unknown>;
+  /** Notified when root objects are added, updated or removed. */
+  addChangeListener(
+    listener: (changes: { adds: unknown[]; updates: unknown[]; removes: unknown[] }) => void,
+  ): void;
+  removeChangeListener(
+    listener: (changes: { adds: unknown[]; updates: unknown[]; removes: unknown[] }) => void,
+  ): void;
+  /** Stop the subscription. Pooled upstream, so re-opening it shortly after is cheap. */
+  close(): void;
+}
+
+/**
+ * Loose shape of `@ng-org/orm`'s `RdfOrmSubscription.getOrCreate` - the SDK's shape
+ * query, reached WITHOUT a framework adapter.
+ *
+ * An application injects the real one (`ormSubscription: RdfOrmSubscription.getOrCreate`);
+ * it is assignable to this as it stands, with no wrapper and no cast. `useShape` is not a
+ * substitute: it is React's hook, it returns a bare `DeepSignalSet`, and a set cannot
+ * carry the request state `ShapeQuery` publishes.
+ */
+// @provenance OrmSubscriptionLike kind=invention level=none ref=none - nothing upstream is injected; the type exists only to describe what `configure` receives, here for the ORM's own `getOrCreate`
+export type OrmSubscriptionLike = <T extends BaseType>(
+  shapeType: ShapeType<T>,
+  scope: Scope,
+) => OrmSubscriptionHandle;
+
 /**
  * The stores that can carry an inbox. NOT `StoreType`: upstream only the public and
  * protected store repos get one — `new_store_default` attaches an inbox solely