@coasys/ad4m 0.13.1-staging.1 → 0.13.1-staging.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (222) hide show
  1. package/lib/index.cjs +3789 -1192
  2. package/lib/index.js +3783 -1193
  3. package/lib/src/generated/api/AgentsByDidsRequest.d.ts +3 -0
  4. package/lib/src/generated/api/CallSessionInfo.d.ts +23 -0
  5. package/lib/src/generated/api/DiscardBatchRequest.d.ts +3 -0
  6. package/lib/src/generated/api/Events.d.ts +13 -3
  7. package/lib/src/generated/api/Events.js +1 -0
  8. package/lib/src/generated/api/FlowStateChangedEvent.d.ts +38 -0
  9. package/lib/src/generated/api/FlowStateEntry.d.ts +18 -0
  10. package/lib/src/generated/api/FlowStateEntry.js +2 -0
  11. package/lib/src/generated/api/IceServer.d.ts +18 -0
  12. package/lib/src/generated/api/IceServer.js +2 -0
  13. package/lib/src/generated/api/OnlineAgent.d.ts +4 -0
  14. package/lib/src/generated/api/PerspectiveDiscardBatchParams.d.ts +4 -0
  15. package/lib/src/generated/api/PerspectiveDiscardBatchParams.js +2 -0
  16. package/lib/src/generated/api/PerspectiveFlowFiredParams.d.ts +8 -0
  17. package/lib/src/generated/api/PerspectiveFlowFiredParams.js +2 -0
  18. package/lib/src/generated/api/PerspectiveFlowStatesParams.d.ts +11 -0
  19. package/lib/src/generated/api/PerspectiveFlowStatesParams.js +2 -0
  20. package/lib/src/generated/api/PerspectiveGetAllShaclParams.d.ts +7 -0
  21. package/lib/src/generated/api/PerspectiveGetAllShaclParams.js +2 -0
  22. package/lib/src/generated/api/PerspectiveModelQueryParams.d.ts +6 -1
  23. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.d.ts +6 -0
  24. package/lib/src/generated/api/PerspectiveRemoveSubjectParams.js +2 -0
  25. package/lib/src/generated/api/PerspectiveResynced.d.ts +8 -0
  26. package/lib/src/generated/api/PerspectiveResynced.js +2 -0
  27. package/lib/src/generated/api/PerspectiveSubscribed.d.ts +10 -0
  28. package/lib/src/generated/api/PerspectiveSubscribed.js +2 -0
  29. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.d.ts +10 -0
  30. package/lib/src/generated/api/PerspectiveUpdateSubjectParams.js +2 -0
  31. package/lib/src/generated/api/QuerySubscriptionUpdate.d.ts +19 -0
  32. package/lib/src/generated/api/QuerySubscriptionUpdate.js +2 -0
  33. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.d.ts +7 -0
  34. package/lib/src/generated/api/QuerySubscriptionUpdateEvent.js +1 -0
  35. package/lib/src/generated/api/QueryUpdatesLagged.d.ts +7 -0
  36. package/lib/src/generated/api/QueryUpdatesLagged.js +2 -0
  37. package/lib/src/generated/api/RemoveSubjectRequest.d.ts +9 -0
  38. package/lib/src/generated/api/RemoveSubjectRequest.js +2 -0
  39. package/lib/src/generated/api/ResyncSubscriptionRequest.d.ts +3 -0
  40. package/lib/src/generated/api/ResyncSubscriptionRequest.js +2 -0
  41. package/lib/src/generated/api/RpcMethods.d.ts +134 -14
  42. package/lib/src/generated/api/RpcMethods.js +12 -0
  43. package/lib/src/generated/api/SfuAddIceCandidateParams.d.ts +8 -0
  44. package/lib/src/generated/api/SfuAddIceCandidateParams.js +2 -0
  45. package/lib/src/generated/api/SfuAnswerServerOfferParams.d.ts +8 -0
  46. package/lib/src/generated/api/SfuAnswerServerOfferParams.js +2 -0
  47. package/lib/src/generated/api/SfuCallJoinParams.d.ts +14 -0
  48. package/lib/src/generated/api/SfuCallJoinParams.js +2 -0
  49. package/lib/src/generated/api/SfuCallRenegotiationOffer.d.ts +30 -0
  50. package/lib/src/generated/api/SfuCallRenegotiationOffer.js +1 -0
  51. package/lib/src/generated/api/SfuCascadePipe.d.ts +4 -0
  52. package/lib/src/generated/api/SfuCascadePipe.js +2 -0
  53. package/lib/src/generated/api/SfuCascadeStatus.d.ts +8 -0
  54. package/lib/src/generated/api/SfuCascadeStatus.js +1 -0
  55. package/lib/src/generated/api/SfuConfig.d.ts +52 -0
  56. package/lib/src/generated/api/SfuConfig.js +1 -0
  57. package/lib/src/generated/api/SfuDataMessage.d.ts +24 -0
  58. package/lib/src/generated/api/SfuDataMessage.js +2 -0
  59. package/lib/src/generated/api/SfuEnsureMembershipParams.d.ts +4 -0
  60. package/lib/src/generated/api/SfuEnsureMembershipParams.js +2 -0
  61. package/lib/src/generated/api/SfuMigrateEvent.d.ts +21 -0
  62. package/lib/src/generated/api/SfuMigrateEvent.js +2 -0
  63. package/lib/src/generated/api/SfuNeighbourhoodParams.d.ts +3 -0
  64. package/lib/src/generated/api/SfuNeighbourhoodParams.js +2 -0
  65. package/lib/src/generated/api/SfuParticipantQualityPreference.d.ts +7 -0
  66. package/lib/src/generated/api/SfuParticipantQualityPreference.js +2 -0
  67. package/lib/src/generated/api/SfuPerspectiveParams.d.ts +6 -0
  68. package/lib/src/generated/api/SfuPerspectiveParams.js +2 -0
  69. package/lib/src/generated/api/SfuQualityPreferenceParams.d.ts +8 -0
  70. package/lib/src/generated/api/SfuQualityPreferenceParams.js +2 -0
  71. package/lib/src/generated/api/SfuRoomInfo.d.ts +11 -0
  72. package/lib/src/generated/api/SfuRoomInfo.js +1 -0
  73. package/lib/src/generated/api/SfuRoomParams.d.ts +4 -0
  74. package/lib/src/generated/api/SfuRoomParams.js +2 -0
  75. package/lib/src/generated/api/SfuRoomParticipantInfo.d.ts +11 -0
  76. package/lib/src/generated/api/SfuRoomParticipantInfo.js +2 -0
  77. package/lib/src/generated/api/SfuRoomRoster.d.ts +13 -0
  78. package/lib/src/generated/api/SfuRoomRoster.js +2 -0
  79. package/lib/src/generated/api/SfuSendDataParams.d.ts +10 -0
  80. package/lib/src/generated/api/SfuSendDataParams.js +2 -0
  81. package/lib/src/generated/api/SfuSetConfigParams.d.ts +5 -0
  82. package/lib/src/generated/api/SfuSetConfigParams.js +1 -0
  83. package/lib/src/generated/api/SfuStatus.d.ts +24 -0
  84. package/lib/src/generated/api/SfuStatus.js +2 -0
  85. package/lib/src/generated/api/TrackMapEntry.d.ts +17 -0
  86. package/lib/src/generated/api/TrackMapEntry.js +2 -0
  87. package/lib/src/generated/api/UpdateSubjectRequest.d.ts +12 -0
  88. package/lib/src/generated/api/UpdateSubjectRequest.js +2 -0
  89. package/lib/src/generated/api/index.d.ts +3 -0
  90. package/lib/src/index.d.ts +7 -0
  91. package/lib/src/index.js +4 -0
  92. package/lib/src/model/Ad4mModel.d.ts +84 -0
  93. package/lib/src/model/Ad4mModel.js +234 -4
  94. package/lib/src/model/ModelQueryBuilder.d.ts +16 -35
  95. package/lib/src/model/ModelQueryBuilder.js +88 -270
  96. package/lib/src/model/decorators.d.ts +32 -0
  97. package/lib/src/model/decorators.js +40 -1
  98. package/lib/src/model/shacl-gen.d.ts +3 -1
  99. package/lib/src/model/shacl-gen.js +13 -1
  100. package/lib/src/model/types.d.ts +7 -0
  101. package/lib/src/neighbourhood/MeshManager.d.ts +384 -0
  102. package/lib/src/neighbourhood/MeshManager.js +1144 -0
  103. package/lib/src/neighbourhood/NeighbourhoodClient.d.ts +91 -0
  104. package/lib/src/neighbourhood/NeighbourhoodClient.js +196 -0
  105. package/lib/src/neighbourhood/NeighbourhoodProxy.d.ts +55 -1
  106. package/lib/src/neighbourhood/NeighbourhoodProxy.js +170 -3
  107. package/lib/src/neighbourhood/Session.d.ts +105 -0
  108. package/lib/src/neighbourhood/Session.js +412 -0
  109. package/lib/src/neighbourhood/SfuManager.d.ts +174 -0
  110. package/lib/src/neighbourhood/SfuManager.js +619 -0
  111. package/lib/src/neighbourhood/SfuTypes.d.ts +35 -0
  112. package/lib/src/neighbourhood/SfuTypes.js +8 -0
  113. package/lib/src/perspectives/FlowInstance.d.ts +63 -24
  114. package/lib/src/perspectives/FlowInstance.js +74 -31
  115. package/lib/src/perspectives/FlowModels.d.ts +0 -16
  116. package/lib/src/perspectives/FlowModels.js +8 -16
  117. package/lib/src/perspectives/LiveQuery.d.ts +49 -0
  118. package/lib/src/perspectives/LiveQuery.js +169 -0
  119. package/lib/src/perspectives/PerspectiveClient.d.ts +24 -15
  120. package/lib/src/perspectives/PerspectiveClient.js +33 -36
  121. package/lib/src/perspectives/PerspectiveProxy.d.ts +67 -167
  122. package/lib/src/perspectives/PerspectiveProxy.js +121 -475
  123. package/lib/src/perspectives/TextContent.d.ts +31 -0
  124. package/lib/src/perspectives/TextContent.js +52 -0
  125. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +23 -0
  126. package/lib/src/perspectives/WakerSubscriptionManager.js +58 -17
  127. package/lib/src/shacl/SHACLFlow.d.ts +7 -4
  128. package/lib/src/shacl/SHACLFlow.js +7 -4
  129. package/lib/src/shacl/SHACLShape.d.ts +9 -0
  130. package/lib/src/shacl/SHACLShape.js +37 -0
  131. package/package.json +2 -2
  132. package/pnpm-workspace.yaml +4 -1
  133. package/src/Ad4mClient.test.ts +89 -17
  134. package/src/generated/api/AgentsByDidsRequest.ts +3 -0
  135. package/src/generated/api/CallSessionInfo.ts +20 -0
  136. package/src/generated/api/DiscardBatchRequest.ts +3 -0
  137. package/src/generated/api/Events.ts +14 -3
  138. package/src/generated/api/FlowStateChangedEvent.ts +36 -0
  139. package/src/generated/api/FlowStateEntry.ts +18 -0
  140. package/src/generated/api/IceServer.ts +19 -0
  141. package/src/generated/api/OnlineAgent.ts +6 -1
  142. package/src/generated/api/PerspectiveDiscardBatchParams.ts +3 -0
  143. package/src/generated/api/PerspectiveFlowFiredParams.ts +7 -0
  144. package/src/generated/api/PerspectiveFlowStatesParams.ts +11 -0
  145. package/src/generated/api/PerspectiveGetAllShaclParams.ts +6 -0
  146. package/src/generated/api/PerspectiveModelQueryParams.ts +5 -1
  147. package/src/generated/api/PerspectiveRemoveSubjectParams.ts +3 -0
  148. package/src/generated/api/PerspectiveResynced.ts +7 -0
  149. package/src/generated/api/PerspectiveSubscribed.ts +8 -0
  150. package/src/generated/api/PerspectiveUpdateSubjectParams.ts +7 -0
  151. package/src/generated/api/QuerySubscriptionUpdate.ts +10 -0
  152. package/src/generated/api/QuerySubscriptionUpdateEvent.ts +9 -0
  153. package/src/generated/api/QueryUpdatesLagged.ts +7 -0
  154. package/src/generated/api/RemoveSubjectRequest.ts +7 -0
  155. package/src/generated/api/ResyncSubscriptionRequest.ts +3 -0
  156. package/src/generated/api/RpcMethods.ts +68 -8
  157. package/src/generated/api/SfuAddIceCandidateParams.ts +7 -0
  158. package/src/generated/api/SfuAnswerServerOfferParams.ts +7 -0
  159. package/src/generated/api/SfuCallJoinParams.ts +13 -0
  160. package/src/generated/api/SfuCallRenegotiationOffer.ts +29 -0
  161. package/src/generated/api/SfuCascadePipe.ts +3 -0
  162. package/src/generated/api/SfuCascadeStatus.ts +7 -0
  163. package/src/generated/api/SfuConfig.ts +53 -0
  164. package/src/generated/api/SfuDataMessage.ts +23 -0
  165. package/src/generated/api/SfuEnsureMembershipParams.ts +3 -0
  166. package/src/generated/api/SfuMigrateEvent.ts +20 -0
  167. package/src/generated/api/{KeepAliveQueryRequest.ts → SfuNeighbourhoodParams.ts} +1 -1
  168. package/src/generated/api/SfuParticipantQualityPreference.ts +6 -0
  169. package/src/generated/api/{PerspectiveSubscribeQueryResult.ts → SfuPerspectiveParams.ts} +4 -1
  170. package/src/generated/api/SfuQualityPreferenceParams.ts +7 -0
  171. package/src/generated/api/SfuRoomInfo.ts +7 -0
  172. package/src/generated/api/SfuRoomParams.ts +3 -0
  173. package/src/generated/api/SfuRoomParticipantInfo.ts +8 -0
  174. package/src/generated/api/SfuRoomRoster.ts +12 -0
  175. package/src/generated/api/SfuSendDataParams.ts +7 -0
  176. package/src/generated/api/SfuSetConfigParams.ts +4 -0
  177. package/src/generated/api/SfuStatus.ts +24 -0
  178. package/src/generated/api/TrackMapEntry.ts +18 -0
  179. package/src/generated/api/UpdateSubjectRequest.ts +10 -0
  180. package/src/generated/api/index.ts +3 -0
  181. package/src/index.ts +7 -0
  182. package/src/model/Ad4mModel.test.ts +255 -231
  183. package/src/model/Ad4mModel.ts +271 -4
  184. package/src/model/ModelQueryBuilder.ts +103 -310
  185. package/src/model/abstract-classes.test.ts +225 -0
  186. package/src/model/decorators.ts +81 -0
  187. package/src/model/shacl-gen.ts +13 -0
  188. package/src/model/types.ts +7 -0
  189. package/src/neighbourhood/MeshManager.test.ts +2640 -0
  190. package/src/neighbourhood/MeshManager.ts +1350 -0
  191. package/src/neighbourhood/NeighbourhoodClient.ts +271 -0
  192. package/src/neighbourhood/NeighbourhoodProxy.test.ts +23 -0
  193. package/src/neighbourhood/NeighbourhoodProxy.ts +247 -1
  194. package/src/neighbourhood/Session.test.ts +800 -0
  195. package/src/neighbourhood/Session.ts +525 -0
  196. package/src/neighbourhood/SfuManager.test.ts +677 -0
  197. package/src/neighbourhood/SfuManager.ts +803 -0
  198. package/src/neighbourhood/SfuTypes.ts +40 -0
  199. package/src/perspectives/FlowInstance.ts +108 -31
  200. package/src/perspectives/FlowModels.ts +8 -18
  201. package/src/perspectives/LiveQuery.test.ts +197 -0
  202. package/src/perspectives/LiveQuery.ts +189 -0
  203. package/src/perspectives/PerspectiveClient.ts +51 -51
  204. package/src/perspectives/PerspectiveProxy.test.ts +85 -401
  205. package/src/perspectives/PerspectiveProxy.ts +126 -536
  206. package/src/perspectives/TextContent.test.ts +123 -0
  207. package/src/perspectives/TextContent.ts +36 -0
  208. package/src/perspectives/WakerSubscriptionManager.test.ts +88 -6
  209. package/src/perspectives/WakerSubscriptionManager.ts +69 -18
  210. package/src/shacl/SHACLFlow.ts +7 -4
  211. package/src/shacl/SHACLShape.test.ts +2 -1
  212. package/src/shacl/SHACLShape.ts +49 -0
  213. package/lib/src/generated/api/KeepAliveQueryRequest.d.ts +0 -3
  214. package/lib/src/generated/api/PerspectiveModelSubscribeResult.d.ts +0 -7
  215. package/lib/src/generated/api/PerspectiveQuerySubscriptionFilter.d.ts +0 -6
  216. package/lib/src/generated/api/PerspectiveSubscribeQueryResult.d.ts +0 -4
  217. package/src/generated/api/PerspectiveModelSubscribeResult.ts +0 -6
  218. package/src/generated/api/PerspectiveQuerySubscriptionFilter.ts +0 -3
  219. /package/lib/src/generated/api/{KeepAliveQueryRequest.js → AgentsByDidsRequest.js} +0 -0
  220. /package/lib/src/generated/api/{PerspectiveModelSubscribeResult.js → CallSessionInfo.js} +0 -0
  221. /package/lib/src/generated/api/{PerspectiveQuerySubscriptionFilter.js → DiscardBatchRequest.js} +0 -0
  222. /package/lib/src/generated/api/{PerspectiveSubscribeQueryResult.js → FlowStateChangedEvent.js} +0 -0
@@ -1074,12 +1074,23 @@ export class Ad4mModel {
1074
1074
  * Shape resolution happens server-side from the perspective's SHACL triples.
1075
1075
  * @internal
1076
1076
  */
1077
+ /**
1078
+ * The name the executor knows this class by: its class name, or a
1079
+ * built-in abstract class's URI (`ad4m://TextContent`, #1446). The URI is
1080
+ * the class's own static only: a subclass is a class of its own.
1081
+ * @internal
1082
+ */
1083
+ static queriedAs(): string {
1084
+ const builtinUri = Object.prototype.hasOwnProperty.call(this, 'builtinUri') ? (this as any).builtinUri : undefined;
1085
+ return builtinUri || this.getModelMetadata().className;
1086
+ }
1087
+
1077
1088
  static prepareModelQueryParams(
1078
1089
  query: Query = {},
1079
1090
  classNameOverride?: string | null,
1080
1091
  ): { className: string; queryJson: string; metadata: ModelMetadata } {
1081
1092
  const metadata = this.getModelMetadata();
1082
- const className = classNameOverride || metadata.className;
1093
+ const className = classNameOverride || this.queriedAs();
1083
1094
 
1084
1095
  // Expand includeAll: true to a full IncludeMap covering every forward relation.
1085
1096
  if (query.includeAll) {
@@ -1182,6 +1193,185 @@ export class Ad4mModel {
1182
1193
  }
1183
1194
 
1184
1195
 
1196
+ // ── One query over several classes (#1238) ────────────────────────────────
1197
+
1198
+ /**
1199
+ * Build the wire parameters for one query over several classes.
1200
+ *
1201
+ * Each class normalises the query as it would for itself — its polymorphic
1202
+ * include defaults, its `$` projections, its parent predicate — and the
1203
+ * results are merged: includes and projections by key (the first class that
1204
+ * declares a key decides its form; a projection two classes tag with
1205
+ * different target classes is refused), the parent scope only when every
1206
+ * class that can resolve it resolves it to the same predicate.
1207
+ * @internal
1208
+ */
1209
+ static prepareUnionQueryParams(
1210
+ classes: (typeof Ad4mModel)[],
1211
+ query: Query = {},
1212
+ ): { classNames: string[]; queryJson: string } {
1213
+ if (!classes.length) throw new Error('A query over several classes needs at least one class');
1214
+ const { parent, preferClasses, ...rest } = query;
1215
+ const inputs = classes.map((c) => JSON.parse(c.prepareModelQueryParams(rest).queryJson));
1216
+ // A projection is tagged with its relation's target class, at every depth,
1217
+ // and the executor hydrates a list projection (and resolves its `where`)
1218
+ // as that class. Two classes that tag the same key differently cannot share
1219
+ // one form of it, so the key is refused rather than read as the first's.
1220
+ const tags = new Map<string, string>();
1221
+ const collectTags = (node: any, path: string) => {
1222
+ if (!node || typeof node !== 'object') return;
1223
+ for (const [k, v] of Object.entries(node)) {
1224
+ if (k === 'targetClassName' && typeof v === 'string') {
1225
+ const seen = tags.get(path);
1226
+ if (seen !== undefined && seen !== v) {
1227
+ throw new Error(
1228
+ `projection '${path}': the classes resolve it to different target classes ` +
1229
+ `(${seen}, ${v}); query those classes separately`,
1230
+ );
1231
+ }
1232
+ tags.set(path, v);
1233
+ } else {
1234
+ collectTags(v, path ? `${path}.${k}` : k);
1235
+ }
1236
+ }
1237
+ };
1238
+ for (const input of inputs) {
1239
+ collectTags(input.include, 'include');
1240
+ collectTags(input.projections, 'projections');
1241
+ }
1242
+ const merged: any = { ...inputs[0] };
1243
+ if (preferClasses) merged.preferClasses = preferClasses;
1244
+ for (const key of ['include', 'projections'] as const) {
1245
+ const combined = Object.assign({}, ...inputs.map((i) => i[key] ?? {}).reverse());
1246
+ if (Object.keys(combined).length) merged[key] = combined;
1247
+ else delete merged[key];
1248
+ }
1249
+ if (parent) {
1250
+ // A model-form scope names its predicate through the relation that
1251
+ // targets the queried class, so each class may resolve it differently
1252
+ // or not at all. One query has one scope.
1253
+ const scopes: string[] = [];
1254
+ let firstError: unknown;
1255
+ for (const c of classes) {
1256
+ try {
1257
+ scopes.push(JSON.stringify(JSON.parse(c.prepareModelQueryParams({ parent }).queryJson).parent));
1258
+ } catch (e) {
1259
+ firstError ??= e;
1260
+ }
1261
+ }
1262
+ if (!scopes.length) throw firstError;
1263
+ if (new Set(scopes).size > 1) {
1264
+ throw new Error(
1265
+ 'parent(): the classes resolve the parent scope to different predicates; ' +
1266
+ 'pass the predicate itself (or a `field`) so they share one scope',
1267
+ );
1268
+ }
1269
+ merged.parent = JSON.parse(scopes[0]);
1270
+ }
1271
+ return {
1272
+ classNames: classes.map((c) => c.queriedAs()),
1273
+ queryJson: JSON.stringify(merged),
1274
+ };
1275
+ }
1276
+
1277
+ /**
1278
+ * Build each row of a union result as the class the executor hydrated it as
1279
+ * (`__subjectClass`). A row of a class not in `classes` stays plain JSON.
1280
+ * @internal
1281
+ */
1282
+ static parseUnionResult(
1283
+ classes: (typeof Ad4mModel)[],
1284
+ perspective: PerspectiveProxy,
1285
+ raw: any,
1286
+ include?: IncludeMap,
1287
+ properties?: string[],
1288
+ ): Ad4mModel[] {
1289
+ const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
1290
+ const arr = data.instances || data;
1291
+ if (!Array.isArray(arr)) return [];
1292
+ const byName = new Map(classes.map((c) => [c.getModelMetadata().className, c]));
1293
+ return arr.map((json: any) => {
1294
+ const cls = byName.get(json?.[SUBJECT_CLASS_KEY]);
1295
+ return cls ? jsonToModelInstance(cls as any, perspective, json, include, properties) : json;
1296
+ });
1297
+ }
1298
+
1299
+ /** @internal */
1300
+ static async executeUnionQuery(
1301
+ perspective: PerspectiveProxy,
1302
+ classes: (typeof Ad4mModel)[],
1303
+ query: Query = {},
1304
+ options?: CallOptions,
1305
+ ): Promise<ResultsWithTotalCount<Ad4mModel>> {
1306
+ const { classNames, queryJson } = Ad4mModel.prepareUnionQueryParams(classes, query);
1307
+ const result = await perspective.modelQuery(classNames, queryJson, options);
1308
+ const results = Ad4mModel.parseUnionResult(classes, perspective, result, query.include, query.properties);
1309
+ const snapshotRelations = query.include
1310
+ ? Object.fromEntries(Object.entries(query.include).filter(([k]) => !k.startsWith('$')))
1311
+ : undefined;
1312
+ for (const inst of results) {
1313
+ (inst as any).takeSnapshot?.(
1314
+ snapshotRelations && Object.keys(snapshotRelations).length > 0 ? snapshotRelations : undefined,
1315
+ );
1316
+ }
1317
+ return { results, totalCount: result.totalCount };
1318
+ }
1319
+
1320
+ /**
1321
+ * One query over several model classes (#1238).
1322
+ *
1323
+ * `where`, `order`, `limit` and `offset` apply once, over the union. Each
1324
+ * result is an instance of the class the executor hydrated it as: the first
1325
+ * `preferClasses` entry it conforms to, otherwise the most specific of
1326
+ * `classes` it conforms to. A record that is several of them is returned
1327
+ * once; `__subjectClasses` on it names every class it conforms to.
1328
+ *
1329
+ * - `where` on a property a class does not declare excludes that class's rows.
1330
+ * - `order` on such a property sorts those rows last, in both directions,
1331
+ * then by id.
1332
+ *
1333
+ * @example
1334
+ * ```typescript
1335
+ * const items = await Ad4mModel.findAllOf(perspective, [Placement, EdgeRoute], {
1336
+ * parent: { id: canvas.id, predicate: "canvas://item" },
1337
+ * order: { zIndex: "ASC" },
1338
+ * limit: 50,
1339
+ * });
1340
+ * for (const item of items) {
1341
+ * if (item instanceof Placement) { ... }
1342
+ * }
1343
+ * ```
1344
+ */
1345
+ static async findAllOf<C extends (typeof Ad4mModel)[]>(
1346
+ perspective: PerspectiveProxy,
1347
+ classes: [...C],
1348
+ query?: Query,
1349
+ options?: CallOptions,
1350
+ ): Promise<InstanceType<C[number]>[]> {
1351
+ const { results } = await Ad4mModel.executeUnionQuery(perspective, classes, query ?? {}, options);
1352
+ return results as InstanceType<C[number]>[];
1353
+ }
1354
+
1355
+ /**
1356
+ * A {@link ModelQueryBuilder} over several model classes: the builder form of
1357
+ * {@link findAllOf}. `subscribe()` registers one subscription, which re-runs
1358
+ * when any of the classes changes.
1359
+ *
1360
+ * @example
1361
+ * ```typescript
1362
+ * const builder = Ad4mModel.queryOf(perspective, [Placement, EdgeRoute])
1363
+ * .parent(canvas.id, "canvas://item");
1364
+ * await builder.subscribe((items) => render(items));
1365
+ * ```
1366
+ */
1367
+ static queryOf<C extends (typeof Ad4mModel)[]>(
1368
+ perspective: PerspectiveProxy,
1369
+ classes: [...C],
1370
+ query?: Query,
1371
+ ): ModelQueryBuilder<InstanceType<C[number]>> {
1372
+ return new ModelQueryBuilder<InstanceType<C[number]>>(perspective, Ad4mModel, query, classes);
1373
+ }
1374
+
1185
1375
  // instancesFromQueryResult — removed (superseded by Rust executeModelQuery pipeline)
1186
1376
 
1187
1377
  /**
@@ -1429,12 +1619,32 @@ export class Ad4mModel {
1429
1619
  return String(value);
1430
1620
  }
1431
1621
 
1622
+ /** A relation write on a row read through an abstract class (#1435). The
1623
+ * relation's predicate is the abstract class's, which no record's class
1624
+ * reads: the executor runs the adder, remover or setter of each of the
1625
+ * record's classes for the relation answering to `key`. */
1626
+ private async relationThroughAbstract(
1627
+ abstractName: string,
1628
+ key: string,
1629
+ action: 'adder' | 'remover' | 'setter',
1630
+ value: any,
1631
+ batchId?: string
1632
+ ) {
1633
+ const ids = (Array.isArray(value) ? value : [value]).map((v) => this.resolveRelationId(v));
1634
+ await this._perspective.updateSubject(abstractName, this._baseExpression, { [key]: { action, value: ids } }, batchId);
1635
+ }
1636
+
1432
1637
  private async setRelationValues(key: string, value: any, batchId?: string) {
1433
1638
  const metadata = this.getRelationOptions(key);
1434
1639
  if (!metadata) {
1435
1640
  console.warn(`Relation "${key}" has no metadata, skipping`);
1436
1641
  return;
1437
1642
  }
1643
+ const abstractName = this.abstractName();
1644
+ if (abstractName) {
1645
+ if (value != null) await this.relationThroughAbstract(abstractName, key, 'setter', value, batchId);
1646
+ return;
1647
+ }
1438
1648
 
1439
1649
  // Generate actions from metadata (replaces Prolog query)
1440
1650
  const actions = this.generateRelationAction(key, 'setter');
@@ -1459,6 +1669,11 @@ export class Ad4mModel {
1459
1669
  console.warn(`Relation "${key}" has no metadata, skipping`);
1460
1670
  return;
1461
1671
  }
1672
+ const abstractName = this.abstractName();
1673
+ if (abstractName) {
1674
+ if (value != null) await this.relationThroughAbstract(abstractName, key, 'adder', value, batchId);
1675
+ return;
1676
+ }
1462
1677
 
1463
1678
  // Generate actions from metadata (replaces Prolog query)
1464
1679
  const actions = this.generateRelationAction(key, 'adder');
@@ -1482,6 +1697,11 @@ export class Ad4mModel {
1482
1697
  console.warn(`Relation "${key}" has no metadata, skipping`);
1483
1698
  return;
1484
1699
  }
1700
+ const abstractName = this.abstractName();
1701
+ if (abstractName) {
1702
+ if (value != null) await this.relationThroughAbstract(abstractName, key, 'remover', value, batchId);
1703
+ return;
1704
+ }
1485
1705
 
1486
1706
  // Generate actions from metadata (replaces Prolog query)
1487
1707
  const actions = this.generateRelationAction(key, 'remover');
@@ -1528,7 +1748,12 @@ export class Ad4mModel {
1528
1748
  async save(batchId?: string) {
1529
1749
  // Existing instance → update path (has been fetched / hydrated before)
1530
1750
  if (this._snapshot) {
1531
- await this.innerUpdate(true, batchId);
1751
+ const abstractName = this.abstractName();
1752
+ if (abstractName) {
1753
+ await this.perspective.updateSubject(abstractName, this._baseExpression, this.changedValuesForDispatch(), batchId);
1754
+ } else {
1755
+ await this.innerUpdate(true, batchId);
1756
+ }
1532
1757
  if (batchId) {
1533
1758
  // Batch hasn't been committed yet — getData() would fetch stale data
1534
1759
  // and overwrite in-memory values. Just refresh the snapshot so further
@@ -1540,7 +1765,15 @@ export class Ad4mModel {
1540
1765
  return;
1541
1766
  }
1542
1767
 
1543
- // New instance → create path
1768
+ // New instance → create path. The executor refuses an abstract class
1769
+ // too; refusing here keeps the error ahead of the batch.
1770
+ const abstractName = this.abstractName();
1771
+ if (abstractName) {
1772
+ throw new Error(
1773
+ `'${abstractName}' is an abstract class and cannot be created. Create an instance of ` +
1774
+ `a class that has its properties; querying '${abstractName}' reads it.`
1775
+ );
1776
+ }
1544
1777
  let batchCreatedHere = false;
1545
1778
  if(!batchId) {
1546
1779
  batchId = await this.perspective.createBatch()
@@ -1609,6 +1842,38 @@ export class Ad4mModel {
1609
1842
  }
1610
1843
  }
1611
1844
 
1845
+ /** The name the executor knows the class by when it is abstract (#1435):
1846
+ * a built-in's URI (#1446). Through an abstract class, the executor
1847
+ * writes to the record's own classes. */
1848
+ private abstractName(): string | undefined {
1849
+ const ctor = this.constructor as typeof Ad4mModel & { isAbstract?: boolean };
1850
+ return ctor.isAbstract ? ctor.queriedAs() : undefined;
1851
+ }
1852
+
1853
+ private changedValues(): Record<string, any> {
1854
+ return Object.fromEntries(this.changedFields().map((key) => [key, (this as any)[key]]));
1855
+ }
1856
+
1857
+ /** `changedValues()` with each relation's members as IDs, as the relation
1858
+ * helpers send them: a member may be a model instance. An action envelope
1859
+ * (`{ action: "adder", value }`) keeps its action, as `innerUpdate()` runs
1860
+ * it; an action it does not know is a setter there, so it is one here. */
1861
+ private changedValuesForDispatch(): Record<string, any> {
1862
+ const relations = (this.constructor as typeof Ad4mModel).getModelMetadata().relations;
1863
+ const ids = (value: any) =>
1864
+ Array.isArray(value) ? value.map((v) => this.resolveRelationId(v)) : this.resolveRelationId(value);
1865
+ return Object.fromEntries(
1866
+ Object.entries(this.changedValues()).map(([key, value]) => {
1867
+ if (!relations[key] || value == null) return [key, value];
1868
+ if (value.action) {
1869
+ const action = ["adder", "remover", "setter"].includes(value.action) ? value.action : "setter";
1870
+ return [key, { action, value: ids(value.value) }];
1871
+ }
1872
+ return [key, ids(value)];
1873
+ })
1874
+ );
1875
+ }
1876
+
1612
1877
  private cleanCopy() {
1613
1878
  const ctor = this.constructor as typeof Ad4mModel;
1614
1879
  const metadata = ctor.getModelMetadata();
@@ -1869,7 +2134,9 @@ export class Ad4mModel {
1869
2134
  */
1870
2135
  async delete(batchId?: string) {
1871
2136
  const metadata = (this.constructor as typeof Ad4mModel).getModelMetadata();
1872
- const hasDestructor = Object.values(metadata.properties).some(
2137
+ // Through an abstract class (#1435), `removeSubject` runs the destructors
2138
+ // of the record's own classes.
2139
+ const hasDestructor = !!this.abstractName() || Object.values(metadata.properties).some(
1873
2140
  (p) => p.required || p.flag || p.initial !== undefined
1874
2141
  );
1875
2142