@coasys/ad4m 0.13.0-test-1 → 0.13.0-test-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 (94) hide show
  1. package/lib/index.cjs +1392 -777
  2. package/lib/index.js +1376 -775
  3. package/lib/src/Literal.js +6 -5
  4. package/lib/src/agent/AgentClient.d.ts +5 -1
  5. package/lib/src/agent/AgentClient.js +48 -2
  6. package/lib/src/expression/ExpressionRef.js +2 -2
  7. package/lib/src/language/Language.d.ts +41 -3
  8. package/lib/src/model/Ad4mModel.d.ts +28 -28
  9. package/lib/src/model/Ad4mModel.js +129 -101
  10. package/lib/src/model/Ad4mModel.test.js +1543 -535
  11. package/lib/src/model/ModelQueryBuilder.d.ts +48 -34
  12. package/lib/src/model/ModelQueryBuilder.js +163 -78
  13. package/lib/src/model/Subject.js +6 -6
  14. package/lib/src/model/decorators.d.ts +14 -8
  15. package/lib/src/model/decorators.js +41 -14
  16. package/lib/src/model/hydration-batch.d.ts +34 -0
  17. package/lib/src/model/hydration-batch.js +147 -0
  18. package/lib/src/model/hydration.d.ts +3 -3
  19. package/lib/src/model/hydration.js +106 -36
  20. package/lib/src/model/index.d.ts +4 -1
  21. package/lib/src/model/index.js +4 -1
  22. package/lib/src/model/json-schema.js +2 -2
  23. package/lib/src/model/query-cache.d.ts +30 -0
  24. package/lib/src/model/query-cache.js +66 -0
  25. package/lib/src/model/query-cache.test.d.ts +1 -0
  26. package/lib/src/model/query-cache.test.js +43 -0
  27. package/lib/src/model/query-common.d.ts +1 -1
  28. package/lib/src/model/query-common.js +1 -1
  29. package/lib/src/model/query-sparql-batch.d.ts +17 -0
  30. package/lib/src/model/query-sparql-batch.js +260 -0
  31. package/lib/src/model/query-sparql.d.ts +47 -0
  32. package/lib/src/model/query-sparql.js +336 -0
  33. package/lib/src/model/query-utils.d.ts +45 -0
  34. package/lib/src/model/query-utils.js +140 -0
  35. package/lib/src/model/relation-filtering.test.js +15 -15
  36. package/lib/src/model/sdna.js +1 -1
  37. package/lib/src/model/shacl-gen.js +42 -18
  38. package/lib/src/model/subscription-pool.d.ts +39 -0
  39. package/lib/src/model/subscription-pool.js +119 -0
  40. package/lib/src/model/types.d.ts +3 -3
  41. package/lib/src/model/types.js +1 -1
  42. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -17
  43. package/lib/src/perspectives/PerspectiveClient.js +5 -57
  44. package/lib/src/perspectives/PerspectiveProxy.d.ts +51 -30
  45. package/lib/src/perspectives/PerspectiveProxy.js +224 -177
  46. package/lib/src/perspectives/PerspectiveResolver.d.ts +0 -1
  47. package/lib/src/perspectives/PerspectiveResolver.js +0 -11
  48. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +3 -3
  49. package/lib/src/perspectives/WakerSubscriptionManager.js +7 -8
  50. package/lib/src/runtime/RuntimeResolver.d.ts +11 -0
  51. package/lib/src/runtime/RuntimeResolver.js +56 -0
  52. package/lib/src/schema.gql +11 -1
  53. package/lib/src/shacl/SHACLFlow.d.ts +1 -1
  54. package/lib/src/shacl/SHACLFlow.js +9 -9
  55. package/lib/src/shacl/SHACLShape.d.ts +1 -1
  56. package/lib/src/shacl/SHACLShape.js +38 -38
  57. package/lib/src/typeDefs.js +11 -1
  58. package/lib/src/utils.d.ts +6 -6
  59. package/lib/src/utils.js +6 -6
  60. package/package.json +1 -1
  61. package/src/Literal.test.ts +10 -5
  62. package/src/Literal.ts +6 -5
  63. package/src/agent/AgentClient.ts +53 -1
  64. package/src/expression/ExpressionRef.ts +2 -2
  65. package/src/language/Language.ts +48 -3
  66. package/src/model/Ad4mModel.test.ts +1515 -565
  67. package/src/model/Ad4mModel.ts +142 -102
  68. package/src/model/ModelQueryBuilder.ts +185 -86
  69. package/src/model/Subject.ts +6 -6
  70. package/src/model/decorators.ts +51 -22
  71. package/src/model/hydration-batch.ts +205 -0
  72. package/src/model/hydration.ts +102 -39
  73. package/src/model/index.ts +4 -1
  74. package/src/model/json-schema.ts +2 -2
  75. package/src/model/query-cache.test.ts +54 -0
  76. package/src/model/query-cache.ts +79 -0
  77. package/src/model/query-common.ts +1 -1
  78. package/src/model/query-sparql-batch.ts +301 -0
  79. package/src/model/query-sparql.ts +363 -0
  80. package/src/model/{surreal-utils.ts → query-utils.ts} +40 -27
  81. package/src/model/relation-filtering.test.ts +15 -15
  82. package/src/model/sdna.ts +1 -1
  83. package/src/model/shacl-gen.ts +42 -17
  84. package/src/model/subscription-pool.ts +163 -0
  85. package/src/model/types.ts +3 -3
  86. package/src/perspectives/PerspectiveClient.ts +5 -61
  87. package/src/perspectives/PerspectiveProxy.ts +226 -181
  88. package/src/perspectives/PerspectiveResolver.ts +0 -8
  89. package/src/perspectives/WakerSubscriptionManager.ts +8 -9
  90. package/src/runtime/RuntimeResolver.ts +43 -0
  91. package/src/shacl/SHACLFlow.ts +9 -9
  92. package/src/shacl/SHACLShape.ts +39 -39
  93. package/src/utils.ts +6 -6
  94. package/src/model/query-surreal.ts +0 -280
@@ -9,13 +9,13 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
9
9
  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
10
10
  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
11
11
  };
12
- var _QuerySubscriptionProxy_instances, _QuerySubscriptionProxy_uuid, _QuerySubscriptionProxy_subscriptionId, _QuerySubscriptionProxy_client, _QuerySubscriptionProxy_callbacks, _QuerySubscriptionProxy_keepaliveTimer, _QuerySubscriptionProxy_unsubscribe, _QuerySubscriptionProxy_latestResult, _QuerySubscriptionProxy_disposed, _QuerySubscriptionProxy_initialized, _QuerySubscriptionProxy_initResolve, _QuerySubscriptionProxy_initReject, _QuerySubscriptionProxy_initTimeoutId, _QuerySubscriptionProxy_query, _QuerySubscriptionProxy_notifyCallbacks, _PerspectiveProxy_handle, _PerspectiveProxy_client, _PerspectiveProxy_perspectiveLinkAddedCallbacks, _PerspectiveProxy_perspectiveLinkRemovedCallbacks, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks;
12
+ var _QuerySubscriptionProxy_instances, _QuerySubscriptionProxy_uuid, _QuerySubscriptionProxy_subscriptionId, _QuerySubscriptionProxy_client, _QuerySubscriptionProxy_callbacks, _QuerySubscriptionProxy_keepaliveTimer, _QuerySubscriptionProxy_unsubscribe, _QuerySubscriptionProxy_latestResult, _QuerySubscriptionProxy_disposed, _QuerySubscriptionProxy_initialized, _QuerySubscriptionProxy_initResolve, _QuerySubscriptionProxy_initReject, _QuerySubscriptionProxy_initTimeoutId, _QuerySubscriptionProxy_query, _QuerySubscriptionProxy_notifyCallbacks, _PerspectiveProxy_handle, _PerspectiveProxy_client, _PerspectiveProxy_perspectiveLinkAddedCallbacks, _PerspectiveProxy_perspectiveLinkRemovedCallbacks, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, _PerspectiveProxy_perspectiveSyncStateChangeCallbacks, _PerspectiveProxy_ensuredSubjectClasses;
13
13
  import { Link } from "../links/Links";
14
14
  import { LinkQuery } from "./LinkQuery";
15
15
  import { Literal } from "../Literal";
16
16
  import { Subject } from "../model/Subject";
17
17
  import { getPropertiesMetadata, getRelationsMetadata } from "../model/decorators";
18
- import { escapeSurrealString } from "../utils";
18
+ import { getCachedResult, setCachedResult, invalidatePerspectiveCache } from "../model/query-cache";
19
19
  import { SHACLShape } from "../shacl/SHACLShape";
20
20
  import { SHACLFlow } from "../shacl/SHACLFlow";
21
21
  /** Proxy object for a subscribed Prolog query that provides real-time updates
@@ -72,7 +72,6 @@ export class QuerySubscriptionProxy {
72
72
  _QuerySubscriptionProxy_initReject.set(this, void 0);
73
73
  _QuerySubscriptionProxy_initTimeoutId.set(this, void 0);
74
74
  _QuerySubscriptionProxy_query.set(this, void 0);
75
- this.isSurrealDB = false;
76
75
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_uuid, uuid, "f");
77
76
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_query, query, "f");
78
77
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_client, client, "f");
@@ -103,12 +102,7 @@ export class QuerySubscriptionProxy {
103
102
  try {
104
103
  // Initialize the query subscription
105
104
  let initialResult;
106
- if (this.isSurrealDB) {
107
- initialResult = await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").perspectiveSubscribeSurrealQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_query, "f"));
108
- }
109
- else {
110
- initialResult = await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").subscribeQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_query, "f"));
111
- }
105
+ initialResult = await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").subscribeQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_query, "f"));
112
106
  __classPrivateFieldSet(this, _QuerySubscriptionProxy_subscriptionId, initialResult.subscriptionId, "f");
113
107
  // Process the initial result immediately for fast UX
114
108
  if (initialResult.result) {
@@ -161,12 +155,7 @@ export class QuerySubscriptionProxy {
161
155
  if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_disposed, "f"))
162
156
  return;
163
157
  try {
164
- if (this.isSurrealDB) {
165
- await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").perspectiveKeepAliveSurrealQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"));
166
- }
167
- else {
168
- await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").keepAliveQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"));
169
- }
158
+ await __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").keepAliveQuery(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"));
170
159
  }
171
160
  catch (e) {
172
161
  console.error('Error in keepalive:', e);
@@ -273,14 +262,8 @@ export class QuerySubscriptionProxy {
273
262
  }
274
263
  // Tell the backend to dispose of the subscription
275
264
  if (__classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f")) {
276
- if (this.isSurrealDB) {
277
- __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").perspectiveDisposeSurrealQuerySubscription(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"))
278
- .catch(e => console.error('Error disposing surreal query subscription:', e));
279
- }
280
- else {
281
- __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").disposeQuerySubscription(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"))
282
- .catch(e => console.error('Error disposing query subscription:', e));
283
- }
265
+ __classPrivateFieldGet(this, _QuerySubscriptionProxy_client, "f").disposeQuerySubscription(__classPrivateFieldGet(this, _QuerySubscriptionProxy_uuid, "f"), __classPrivateFieldGet(this, _QuerySubscriptionProxy_subscriptionId, "f"))
266
+ .catch(e => console.error('Error disposing query subscription:', e));
284
267
  }
285
268
  }
286
269
  }
@@ -345,6 +328,12 @@ export class PerspectiveProxy {
345
328
  _PerspectiveProxy_perspectiveLinkRemovedCallbacks.set(this, void 0);
346
329
  _PerspectiveProxy_perspectiveLinkUpdatedCallbacks.set(this, void 0);
347
330
  _PerspectiveProxy_perspectiveSyncStateChangeCallbacks.set(this, void 0);
331
+ _PerspectiveProxy_ensuredSubjectClasses.set(this, new Set()
332
+ /**
333
+ * Creates a new PerspectiveProxy instance.
334
+ * Note: Don't create this directly, use ad4m.perspective.add() instead.
335
+ */
336
+ );
348
337
  __classPrivateFieldSet(this, _PerspectiveProxy_perspectiveLinkAddedCallbacks, [], "f");
349
338
  __classPrivateFieldSet(this, _PerspectiveProxy_perspectiveLinkRemovedCallbacks, [], "f");
350
339
  __classPrivateFieldSet(this, _PerspectiveProxy_perspectiveLinkUpdatedCallbacks, [], "f");
@@ -435,7 +424,9 @@ export class PerspectiveProxy {
435
424
  * @param batchId - Optional batch ID to group this operation with others
436
425
  */
437
426
  async executeAction(actions, expression, parameters, batchId) {
438
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").executeCommands(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, JSON.stringify(actions), expression, JSON.stringify(parameters), batchId);
427
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").executeCommands(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, JSON.stringify(actions), expression, JSON.stringify(parameters), batchId);
428
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
429
+ return result;
439
430
  }
440
431
  /**
441
432
  * Retrieves links from the perspective that match the given query.
@@ -488,34 +479,28 @@ export class PerspectiveProxy {
488
479
  return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").queryProlog(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query);
489
480
  }
490
481
  /**
491
- * Executes a SurrealQL query against the perspective's link cache.
492
- * This allows powerful SQL-like queries on the link data stored in SurrealDB.
482
+ * Executes a SPARQL query against the perspective's link cache.
483
+ * This allows powerful SQL-like queries on the link data stored in SPARQL.
493
484
  *
494
485
  * **Security Note:** Only read-only queries (SELECT, RETURN, etc.) are permitted.
495
486
  * Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
496
487
  * blocked for security reasons. Use the perspective's add/remove methods to modify links.
497
488
  *
498
- * @param query - SurrealQL query string (read-only operations only)
489
+ * @param query - SPARQL query string (read-only operations only)
499
490
  * @returns Query results as parsed JSON
500
491
  *
501
- * @example
502
- * ```typescript
503
- * // Get all links
504
- * const links = await perspective.querySurrealDB('SELECT * FROM link');
505
- *
506
- * // Filter links by predicate
507
- * const follows = await perspective.querySurrealDB(
508
- * "SELECT * FROM link WHERE predicate = 'follows'"
509
- * );
510
- *
511
- * // Complex aggregation query
512
- * const stats = await perspective.querySurrealDB(
513
- * "SELECT predicate, count() as total FROM link GROUP BY predicate"
514
- * );
515
- * ```
492
+ * Executes a SPARQL query against the perspective's RDF (Oxigraph) store.
493
+ *
494
+ * @param query - SPARQL query string
495
+ * @returns Query results as parsed JSON
516
496
  */
517
- async querySurrealDB(query) {
518
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").querySurrealDB(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query);
497
+ async querySparql(query) {
498
+ const cached = getCachedResult(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query);
499
+ if (cached !== undefined)
500
+ return cached;
501
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").querySparql(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query);
502
+ setCachedResult(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, query, result);
503
+ return result;
519
504
  }
520
505
  /**
521
506
  * Adds a new link to the perspective.
@@ -543,7 +528,9 @@ export class PerspectiveProxy {
543
528
  * ```
544
529
  */
545
530
  async add(link, status = 'shared', batchId) {
546
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addLink(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, link, status, batchId);
531
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addLink(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, link, status, batchId);
532
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
533
+ return result;
547
534
  }
548
535
  /**
549
536
  * Adds multiple links to the perspective in a single operation.
@@ -555,7 +542,9 @@ export class PerspectiveProxy {
555
542
  * @returns Array of created LinkExpressions
556
543
  */
557
544
  async addLinks(links, status = 'shared', batchId) {
558
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addLinks(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, links, status, batchId);
545
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addLinks(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, links, status, batchId);
546
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
547
+ return result;
559
548
  }
560
549
  /**
561
550
  * Removes multiple links from the perspective.
@@ -565,7 +554,9 @@ export class PerspectiveProxy {
565
554
  * @returns Array of removed LinkExpressions
566
555
  */
567
556
  async removeLinks(links, batchId) {
568
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").removeLinks(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, links, batchId);
557
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").removeLinks(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, links, batchId);
558
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
559
+ return result;
569
560
  }
570
561
  /**
571
562
  * Applies a set of link mutations (adds and removes) in a single operation.
@@ -576,7 +567,9 @@ export class PerspectiveProxy {
576
567
  * @returns Object containing results of the mutations
577
568
  */
578
569
  async linkMutations(mutations, status = 'shared') {
579
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").linkMutations(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, mutations, status);
570
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").linkMutations(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, mutations, status);
571
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
572
+ return result;
580
573
  }
581
574
  /**
582
575
  * Adds a pre-signed LinkExpression to the perspective.
@@ -597,7 +590,9 @@ export class PerspectiveProxy {
597
590
  * @param batchId - Optional batch ID to group this operation with others
598
591
  */
599
592
  async update(oldLink, newLink, batchId) {
600
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").updateLink(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, oldLink, newLink, batchId);
593
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").updateLink(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, oldLink, newLink, batchId);
594
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
595
+ return result;
601
596
  }
602
597
  /**
603
598
  * Removes a link from the perspective.
@@ -606,7 +601,9 @@ export class PerspectiveProxy {
606
601
  * @param batchId - Optional batch ID to group this operation with others
607
602
  */
608
603
  async remove(link, batchId) {
609
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").removeLink(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, link, batchId);
604
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").removeLink(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, link, batchId);
605
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
606
+ return result;
610
607
  }
611
608
  /** Creates a new batch for grouping operations */
612
609
  async createBatch() {
@@ -614,7 +611,9 @@ export class PerspectiveProxy {
614
611
  }
615
612
  /** Commits a batch of operations */
616
613
  async commitBatch(batchId) {
617
- return await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").commitBatch(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, batchId);
614
+ const result = await __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").commitBatch(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, batchId);
615
+ invalidatePerspectiveCache(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
616
+ return result;
618
617
  }
619
618
  /**
620
619
  * Retrieves and renders an Expression referenced in this perspective.
@@ -989,6 +988,13 @@ export class PerspectiveProxy {
989
988
  async addSdna(name, sdnaCode, sdnaType, shaclJson) {
990
989
  return __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").addSdna(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid, name, sdnaCode, sdnaType, shaclJson);
991
990
  }
991
+ /**
992
+ * Adds a subject class to the perspective.
993
+ * Alias for addSdna() with sdnaType='subject_class'.
994
+ */
995
+ async addSubjectClass(name, shaclJson) {
996
+ return this.addSdna(name, '', 'subject_class', shaclJson);
997
+ }
992
998
  /**
993
999
  * **Recommended way to add SDNA schemas.**
994
1000
  *
@@ -1020,7 +1026,7 @@ export class PerspectiveProxy {
1020
1026
  // Serialize shape to links
1021
1027
  const shapeLinks = shape.toLinks();
1022
1028
  // Create name -> shape mapping links
1023
- const nameMapping = Literal.fromUrl(`literal://string:shacl://${name}`);
1029
+ const nameMapping = Literal.fromUrl(`literal:string:shacl://${name}`);
1024
1030
  const allLinks = [
1025
1031
  ...shapeLinks.map(l => new Link({
1026
1032
  source: l.source,
@@ -1046,7 +1052,7 @@ export class PerspectiveProxy {
1046
1052
  */
1047
1053
  async getShacl(name) {
1048
1054
  // Find the shape URI from the name mapping
1049
- const nameMapping = Literal.fromUrl(`literal://string:shacl://${name}`);
1055
+ const nameMapping = Literal.fromUrl(`literal:string:shacl://${name}`);
1050
1056
  const shapeUriLinks = await this.get(new LinkQuery({
1051
1057
  source: nameMapping.toUrl(),
1052
1058
  predicate: "ad4m://shacl_shape_uri"
@@ -1055,22 +1061,25 @@ export class PerspectiveProxy {
1055
1061
  return null;
1056
1062
  }
1057
1063
  const shapeUri = shapeUriLinks[0].data.target;
1058
- const escapedShapeUri = escapeSurrealString(shapeUri);
1059
1064
  // First get property shape URIs so we can query everything in one go
1060
1065
  const propertyLinks = await this.get(new LinkQuery({
1061
1066
  source: shapeUri,
1062
1067
  predicate: "sh://property"
1063
1068
  }));
1064
- // Build a single surreal query that fetches all relevant links
1069
+ // Fetch all links from the shape and its property shapes
1065
1070
  const sourceUris = [shapeUri, ...propertyLinks.map(l => l.data.target)];
1066
- const escapedSources = sourceUris.map(u => `'${escapeSurrealString(u)}'`).join(', ');
1067
- const query = `SELECT in.uri AS source, predicate, out.uri AS target FROM link WHERE in.uri IN [${escapedSources}]`;
1068
- const result = await this.querySurrealDB(query);
1069
- const shapeLinks = (result || []).map((r) => ({
1070
- source: r.source,
1071
- predicate: r.predicate,
1072
- target: r.target
1073
- }));
1071
+ const allLinks = [];
1072
+ for (const uri of sourceUris) {
1073
+ const links = await this.get(new LinkQuery({ source: uri }));
1074
+ for (const l of links) {
1075
+ allLinks.push({
1076
+ source: l.data.source,
1077
+ predicate: l.data.predicate,
1078
+ target: l.data.target
1079
+ });
1080
+ }
1081
+ }
1082
+ const shapeLinks = allLinks;
1074
1083
  return SHACLShape.fromLinks(shapeLinks, shapeUri);
1075
1084
  }
1076
1085
  /**
@@ -1172,19 +1181,20 @@ export class PerspectiveProxy {
1172
1181
  return null;
1173
1182
  }
1174
1183
  const flowUri = flowUriLinks[0].data.target;
1175
- const escapedFlowUri = escapeSurrealString(flowUri);
1176
1184
  // Compute alternate prefix for state/transition URIs
1177
1185
  const alternatePrefix = flowUri.endsWith('Flow')
1178
1186
  ? flowUri.slice(0, -4) + '.'
1179
1187
  : flowUri + '.';
1180
- const escapedAltPrefix = escapeSurrealString(alternatePrefix);
1181
- // Single surreal query to get all flow-related links
1182
- const query = `SELECT in.uri AS source, predicate, out.uri AS target FROM link WHERE in.uri = '${escapedFlowUri}' OR string::starts_with(in.uri, '${escapedAltPrefix}')`;
1183
- const result = await this.querySurrealDB(query);
1184
- const flowLinks = (result || []).map((r) => ({
1185
- source: r.source,
1186
- predicate: r.predicate,
1187
- target: r.target
1188
+ // Fetch flow links using SPARQL to match flowUri source OR alternatePrefix sources
1189
+ const sparqlQuery = `SELECT ?s ?p ?o WHERE {
1190
+ ?s ?p ?o .
1191
+ FILTER(?s = <${flowUri}> || STRSTARTS(STR(?s), "${alternatePrefix}"))
1192
+ }`;
1193
+ const sparqlResult = await this.querySparql(sparqlQuery);
1194
+ const flowLinks = (sparqlResult || []).map((r) => ({
1195
+ source: r.s,
1196
+ predicate: r.p,
1197
+ target: r.o
1188
1198
  }));
1189
1199
  return SHACLFlow.fromLinks(flowLinks, flowUri);
1190
1200
  }
@@ -1293,8 +1303,8 @@ export class PerspectiveProxy {
1293
1303
  const links = await this.get(new LinkQuery({ predicate }));
1294
1304
  for (const link of links) {
1295
1305
  if (shapePattern.test(link.data.source)) {
1296
- // Parse actions from literal://string:{json}
1297
- const prefix = "literal://string:";
1306
+ // Parse actions from literal:string:{json}
1307
+ const prefix = "literal:string:";
1298
1308
  if (link.data.target.startsWith(prefix)) {
1299
1309
  const jsonStr = link.data.target.slice(prefix.length);
1300
1310
  // Decode URL-encoded JSON if needed, with fallback for raw % characters
@@ -1350,35 +1360,20 @@ export class PerspectiveProxy {
1350
1360
  }
1351
1361
  // If no required triples, any expression with links is an instance
1352
1362
  if (metadata.requiredTriples.length === 0) {
1353
- const escapedExpression = escapeSurrealString(expression);
1354
- const checkQuery = `SELECT count() AS count FROM link WHERE in.uri = '${escapedExpression}'`;
1355
- const result = await this.querySurrealDB(checkQuery);
1356
- const count = result[0]?.count ?? 0;
1357
- const countValue = typeof count === 'object' && count?.Int !== undefined ? count.Int : count;
1358
- return countValue > 0;
1363
+ const links = await this.get(new LinkQuery({ source: expression }));
1364
+ return links.length > 0;
1359
1365
  }
1360
1366
  // Check if the expression has all required triples (predicate + optional exact target)
1361
1367
  for (const triple of metadata.requiredTriples) {
1362
- const escapedExpression = escapeSurrealString(expression);
1363
- const escapedPredicate = escapeSurrealString(triple.predicate);
1364
- let checkQuery;
1368
+ let query;
1365
1369
  if (triple.target) {
1366
- // Flag: must match both predicate AND exact target value
1367
- const escapedTarget = escapeSurrealString(triple.target);
1368
- checkQuery = `SELECT count() AS count FROM link WHERE in.uri = '${escapedExpression}' AND predicate = '${escapedPredicate}' AND out.uri = '${escapedTarget}'`;
1370
+ query = new LinkQuery({ source: expression, predicate: triple.predicate, target: triple.target });
1369
1371
  }
1370
1372
  else {
1371
- // Property: just check predicate exists
1372
- checkQuery = `SELECT count() AS count FROM link WHERE in.uri = '${escapedExpression}' AND predicate = '${escapedPredicate}'`;
1373
- }
1374
- const result = await this.querySurrealDB(checkQuery);
1375
- if (!result || result.length === 0) {
1376
- return false;
1373
+ query = new LinkQuery({ source: expression, predicate: triple.predicate });
1377
1374
  }
1378
- const count = result[0]?.count ?? 0;
1379
- // Handle potential object response like {Int: 0}
1380
- const countValue = typeof count === 'object' && count?.Int !== undefined ? count.Int : count;
1381
- if (countValue === 0) {
1375
+ const links = await this.get(query);
1376
+ if (!links || links.length === 0) {
1382
1377
  return false;
1383
1378
  }
1384
1379
  }
@@ -1406,6 +1401,10 @@ export class PerspectiveProxy {
1406
1401
  * Gets subject class metadata from SHACL links using SHACLShape.fromLinks().
1407
1402
  * Retrieves the SHACL shape and extracts metadata for instance queries.
1408
1403
  */
1404
+ async getSubjectClassMetadata(className) {
1405
+ return this.getSubjectClassMetadataFromSDNA(className);
1406
+ }
1407
+ /** @deprecated Use getSubjectClassMetadata() */
1409
1408
  async getSubjectClassMetadataFromSDNA(className) {
1410
1409
  try {
1411
1410
  // Use getShacl() to retrieve the shape via SHACLShape.fromLinks()
@@ -1460,33 +1459,55 @@ export class PerspectiveProxy {
1460
1459
  }
1461
1460
  }
1462
1461
  /**
1463
- * Generates a SurrealDB query to find instances based on class metadata.
1462
+ * Generates a SPARQL query to find instances based on class metadata.
1463
+ */
1464
+ /**
1465
+ * Finds all instances matching subject class metadata by querying links.
1466
+ * Returns base URIs of matching instances.
1464
1467
  */
1465
- generateSurrealInstanceQuery(metadata) {
1468
+ async findInstancesByMetadata(metadata) {
1466
1469
  if (metadata.requiredTriples.length === 0) {
1467
- // No required triples - any node with links is an instance
1468
- return `SELECT DISTINCT uri AS base FROM node WHERE count(->link) > 0`;
1470
+ // No required triples - return all unique sources that have any link
1471
+ const allLinks = await this.get(new LinkQuery({}));
1472
+ const sources = new Set(allLinks.map(l => l.data.source));
1473
+ return Array.from(sources).map(s => ({ base: s }));
1469
1474
  }
1470
- // Generate WHERE conditions for each required triple (predicate + optional exact target)
1471
- const whereConditions = metadata.requiredTriples.map(triple => {
1472
- const escapedPredicate = escapeSurrealString(triple.predicate);
1473
- if (triple.target) {
1474
- // Flag: must match both predicate AND exact target value
1475
- const escapedTarget = escapeSurrealString(triple.target);
1476
- return `count(->link[WHERE predicate = '${escapedPredicate}' AND out.uri = '${escapedTarget}']) > 0`;
1477
- }
1478
- else {
1479
- // Property: just check predicate exists
1480
- return `count(->link[WHERE predicate = '${escapedPredicate}']) > 0`;
1475
+ // Use first required triple to get candidate set, then filter by rest
1476
+ const first = metadata.requiredTriples[0];
1477
+ let query;
1478
+ if (first.target) {
1479
+ query = new LinkQuery({ predicate: first.predicate, target: first.target });
1480
+ }
1481
+ else {
1482
+ query = new LinkQuery({ predicate: first.predicate });
1483
+ }
1484
+ const candidateLinks = await this.get(query);
1485
+ let candidates = [...new Set(candidateLinks.map(l => l.data.source))];
1486
+ // Filter by remaining required triples
1487
+ for (let i = 1; i < metadata.requiredTriples.length; i++) {
1488
+ const triple = metadata.requiredTriples[i];
1489
+ const remaining = [];
1490
+ for (const expr of candidates) {
1491
+ let q;
1492
+ if (triple.target) {
1493
+ q = new LinkQuery({ source: expr, predicate: triple.predicate, target: triple.target });
1494
+ }
1495
+ else {
1496
+ q = new LinkQuery({ source: expr, predicate: triple.predicate });
1497
+ }
1498
+ const links = await this.get(q);
1499
+ if (links.length > 0)
1500
+ remaining.push(expr);
1481
1501
  }
1482
- }).join(' AND ');
1483
- return `SELECT uri AS base FROM node WHERE ${whereConditions}`;
1502
+ candidates = remaining;
1503
+ }
1504
+ return candidates.map(c => ({ base: c }));
1484
1505
  }
1485
1506
  /**
1486
- * Gets a property value using SurrealDB when Prolog fails.
1507
+ * Gets a property value using SPARQL when Prolog fails.
1487
1508
  * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
1488
1509
  */
1489
- async getPropertyValueViaSurreal(baseExpression, className, propertyName) {
1510
+ async getPropertyValueViaSparql(baseExpression, className, propertyName) {
1490
1511
  const metadata = await this.getSubjectClassMetadataFromSDNA(className);
1491
1512
  if (!metadata) {
1492
1513
  return undefined;
@@ -1495,14 +1516,11 @@ export class PerspectiveProxy {
1495
1516
  if (!propMeta) {
1496
1517
  return undefined;
1497
1518
  }
1498
- const escapedBaseExpression = escapeSurrealString(baseExpression);
1499
- const escapedPredicate = escapeSurrealString(propMeta.predicate);
1500
- const query = `SELECT out.uri AS value FROM link WHERE in.uri = '${escapedBaseExpression}' AND predicate = '${escapedPredicate}' LIMIT 1`;
1501
- const result = await this.querySurrealDB(query);
1502
- if (!result || result.length === 0) {
1519
+ const links = await this.get(new LinkQuery({ source: baseExpression, predicate: propMeta.predicate }));
1520
+ if (!links || links.length === 0) {
1503
1521
  return undefined;
1504
1522
  }
1505
- const value = result[0].value;
1523
+ const value = links[0].data.target;
1506
1524
  // Handle expression resolution if needed
1507
1525
  if (propMeta.resolveLanguage && value) {
1508
1526
  try {
@@ -1521,11 +1539,11 @@ export class PerspectiveProxy {
1521
1539
  return value;
1522
1540
  }
1523
1541
  /**
1524
- * Gets relation values using SurrealDB when Prolog fails.
1542
+ * Gets relation values using SPARQL when Prolog fails.
1525
1543
  * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
1526
1544
  * Note: This is used by Subject.ts (legacy pattern). Ad4mModel.ts uses getModelMetadata() instead.
1527
1545
  */
1528
- async getRelationValuesViaSurreal(baseExpression, className, relationName) {
1546
+ async getRelationValuesViaSparql(baseExpression, className, relationName) {
1529
1547
  const metadata = await this.getSubjectClassMetadataFromSDNA(className);
1530
1548
  if (!metadata) {
1531
1549
  return [];
@@ -1534,14 +1552,13 @@ export class PerspectiveProxy {
1534
1552
  if (!relMeta) {
1535
1553
  return [];
1536
1554
  }
1537
- const escapedBaseExpression = escapeSurrealString(baseExpression);
1538
- const escapedPredicate = escapeSurrealString(relMeta.predicate);
1539
- const query = `SELECT out.uri AS value, timestamp FROM link WHERE in.uri = '${escapedBaseExpression}' AND predicate = '${escapedPredicate}' ORDER BY timestamp ASC`;
1540
- const result = await this.querySurrealDB(query);
1541
- if (!result || result.length === 0) {
1555
+ const links = await this.get(new LinkQuery({ source: baseExpression, predicate: relMeta.predicate }));
1556
+ if (!links || links.length === 0) {
1542
1557
  return [];
1543
1558
  }
1544
- let values = result.map(r => r.value).filter(v => v !== "" && v !== '');
1559
+ // Sort by timestamp ascending
1560
+ links.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
1561
+ let values = links.map(l => l.data.target).filter(v => v !== "" && v !== '');
1545
1562
  // Apply condition filtering if present
1546
1563
  if (relMeta.condition && values.length > 0) {
1547
1564
  try {
@@ -1551,13 +1568,28 @@ export class PerspectiveProxy {
1551
1568
  .replace(/\$perspective/g, `'${this.uuid}'`)
1552
1569
  .replace(/\$base/g, `'${baseExpression}'`)
1553
1570
  .replace(/Target/g, `'${value.replace(/'/g, "\\'")}'`);
1554
- // If condition starts with WHERE, wrap in array length check
1555
- if (condition.trim().startsWith('WHERE')) {
1556
- condition = `array::len(SELECT * FROM link ${condition}) > 0`;
1571
+ // Parse condition to extract link query parameters
1572
+ // Conditions typically look like: WHERE in.uri = 'X' AND predicate = 'Y' AND out.uri = 'Z'
1573
+ // or: array::len(SELECT * FROM link WHERE ...) > 0
1574
+ // Convert to queryLinks calls
1575
+ const sourceMatch = condition.match(/in\.uri\s*=\s*'([^']+)'/);
1576
+ const predicateMatch = condition.match(/predicate\s*=\s*'([^']+)'/);
1577
+ const targetMatch = condition.match(/out\.uri\s*=\s*'([^']+)'/);
1578
+ if (sourceMatch || predicateMatch || targetMatch) {
1579
+ const linkQuery = {};
1580
+ if (sourceMatch)
1581
+ linkQuery.source = sourceMatch[1];
1582
+ if (predicateMatch)
1583
+ linkQuery.predicate = predicateMatch[1];
1584
+ if (targetMatch)
1585
+ linkQuery.target = targetMatch[1];
1586
+ const matchingLinks = await this.get(new LinkQuery(linkQuery));
1587
+ if (matchingLinks.length > 0) {
1588
+ filteredValues.push(value);
1589
+ }
1557
1590
  }
1558
- const filterResult = await this.querySurrealDB(`RETURN ${condition}`);
1559
- const isTrue = filterResult === true || (Array.isArray(filterResult) && filterResult.length > 0 && filterResult[0] === true);
1560
- if (isTrue) {
1591
+ else {
1592
+ // Can't parse condition, include by default
1561
1593
  filteredValues.push(value);
1562
1594
  }
1563
1595
  }
@@ -1585,7 +1617,7 @@ export class PerspectiveProxy {
1585
1617
  return values;
1586
1618
  }
1587
1619
  /**
1588
- * Batch-checks multiple expressions against subject class metadata using a single or limited SurrealDB queries.
1620
+ * Batch-checks multiple expressions against subject class metadata using a single or limited SPARQL queries.
1589
1621
  * This avoids N+1 query problems by checking all values at once.
1590
1622
  */
1591
1623
  async batchCheckSubjectInstances(expressions, metadata) {
@@ -1594,30 +1626,31 @@ export class PerspectiveProxy {
1594
1626
  }
1595
1627
  // If no required triples, check which expressions have any links
1596
1628
  if (metadata.requiredTriples.length === 0) {
1597
- const escapedExpressions = expressions.map(e => `'${escapeSurrealString(e)}'`).join(', ');
1598
- const checkQuery = `SELECT in.uri AS uri FROM link WHERE in.uri IN [${escapedExpressions}] GROUP BY in.uri HAVING count() > 0`;
1599
- const result = await this.querySurrealDB(checkQuery);
1600
- return result.map(r => r.uri);
1629
+ const results = [];
1630
+ for (const expr of expressions) {
1631
+ const links = await this.get(new LinkQuery({ source: expr }));
1632
+ if (links.length > 0)
1633
+ results.push(expr);
1634
+ }
1635
+ return results;
1601
1636
  }
1602
- // For each required triple, build a query that finds matching expressions
1637
+ // For each required triple, find which expressions match
1603
1638
  const validExpressionSets = [];
1604
1639
  for (const triple of metadata.requiredTriples) {
1605
- const escapedExpressions = expressions.map(e => `'${escapeSurrealString(e)}'`).join(', ');
1606
- const escapedPredicate = escapeSurrealString(triple.predicate);
1607
- let checkQuery;
1608
- if (triple.target) {
1609
- // Flag: must match both predicate AND exact target value
1610
- const escapedTarget = escapeSurrealString(triple.target);
1611
- // Note: Removed GROUP BY because it was causing SurrealDB to only return one result
1612
- checkQuery = `SELECT in.uri AS uri FROM link WHERE in.uri IN [${escapedExpressions}] AND predicate = '${escapedPredicate}' AND out.uri = '${escapedTarget}'`;
1613
- }
1614
- else {
1615
- // Property: just check predicate exists
1616
- // Note: Removed GROUP BY because it was causing SurrealDB to only return one result
1617
- checkQuery = `SELECT in.uri AS uri FROM link WHERE in.uri IN [${escapedExpressions}] AND predicate = '${escapedPredicate}'`;
1640
+ const matchingExprs = new Set();
1641
+ for (const expr of expressions) {
1642
+ let query;
1643
+ if (triple.target) {
1644
+ query = new LinkQuery({ source: expr, predicate: triple.predicate, target: triple.target });
1645
+ }
1646
+ else {
1647
+ query = new LinkQuery({ source: expr, predicate: triple.predicate });
1648
+ }
1649
+ const links = await this.get(query);
1650
+ if (links.length > 0)
1651
+ matchingExprs.add(expr);
1618
1652
  }
1619
- const result = await this.querySurrealDB(checkQuery);
1620
- validExpressionSets.push(new Set(result.map(r => r.uri)));
1653
+ validExpressionSets.push(matchingExprs);
1621
1654
  }
1622
1655
  // Find intersection: expressions that passed ALL required triple checks
1623
1656
  if (validExpressionSets.length === 0) {
@@ -1670,13 +1703,12 @@ export class PerspectiveProxy {
1670
1703
  let instances = [];
1671
1704
  for (let className of classes) {
1672
1705
  //console.log(`getAllSubjectInstances: Processing class ${className}`);
1673
- // Query SDNA for metadata, then query SurrealDB for instances
1706
+ // Query SDNA for metadata, then query SPARQL for instances
1674
1707
  const metadata = await this.getSubjectClassMetadataFromSDNA(className);
1675
1708
  //console.log(`getAllSubjectInstances: Got metadata for ${className}:`, metadata);
1676
1709
  if (metadata) {
1677
- const surrealQuery = this.generateSurrealInstanceQuery(metadata);
1678
- const results = await this.querySurrealDB(surrealQuery);
1679
- // console.log(`getAllSubjectInstances: SurrealDB returned ${results?.length || 0} results`);
1710
+ const results = await this.findInstancesByMetadata(metadata);
1711
+ // console.log(`getAllSubjectInstances: SPARQL returned ${results?.length || 0} results`);
1680
1712
  for (const result of results || []) {
1681
1713
  //console.log(`getAllSubjectInstances: Creating subject for base ${result.base}`);
1682
1714
  try {
@@ -1723,11 +1755,10 @@ export class PerspectiveProxy {
1723
1755
  }
1724
1756
  let instances = [];
1725
1757
  for (let className of classes) {
1726
- // Query SDNA for metadata, then query SurrealDB for instances
1758
+ // Query SDNA for metadata, then query SPARQL for instances
1727
1759
  const metadata = await this.getSubjectClassMetadataFromSDNA(className);
1728
1760
  if (metadata) {
1729
- const surrealQuery = this.generateSurrealInstanceQuery(metadata);
1730
- const results = await this.querySurrealDB(surrealQuery);
1761
+ const results = await this.findInstancesByMetadata(metadata);
1731
1762
  for (const result of results || []) {
1732
1763
  try {
1733
1764
  let subject = new Subject(this, result.base, className);
@@ -1772,15 +1803,16 @@ export class PerspectiveProxy {
1772
1803
  if (properties.length === 0 && relations.length === 0) {
1773
1804
  return null;
1774
1805
  }
1775
- // Single SurrealDB query to find all classes and their properties/relations
1776
- const query = `SELECT
1777
- in.uri AS shape_source,
1778
- predicate,
1779
- out.uri AS target
1780
- FROM link
1781
- WHERE predicate IN ['rdf://type', 'sh://property', 'sh://collection']`;
1782
- const results = await this.querySurrealDB(query);
1783
- if (!results || results.length === 0)
1806
+ // Query links for class shapes using queryLinks
1807
+ const typeLinks = await this.get(new LinkQuery({ predicate: 'rdf://type', target: 'ad4m://SubjectClass' }));
1808
+ const propLinks = await this.get(new LinkQuery({ predicate: 'sh://property' }));
1809
+ const collLinks = await this.get(new LinkQuery({ predicate: 'sh://collection' }));
1810
+ const results = [
1811
+ ...typeLinks.map(l => ({ shape_source: l.data.source, predicate: l.data.predicate, target: l.data.target })),
1812
+ ...propLinks.map(l => ({ shape_source: l.data.source, predicate: l.data.predicate, target: l.data.target })),
1813
+ ...collLinks.map(l => ({ shape_source: l.data.source, predicate: l.data.predicate, target: l.data.target })),
1814
+ ];
1815
+ if (results.length === 0)
1784
1816
  return null;
1785
1817
  // Build a map of className -> { properties, relations }
1786
1818
  const classShapes = new Map();
@@ -1878,8 +1910,15 @@ export class PerspectiveProxy {
1878
1910
  * static generateSDNA() function and adds it to the perspective's SDNA.
1879
1911
  */
1880
1912
  async ensureSDNASubjectClass(jsClass) {
1913
+ return this.ensureSubjectClass(jsClass);
1914
+ }
1915
+ /** Takes a JS class (its constructor) and ensures the SHACL subject class exists. */
1916
+ async ensureSubjectClass(jsClass) {
1881
1917
  // Get the class name from the JS class
1882
1918
  const className = jsClass.className || jsClass.prototype?.className || jsClass.name;
1919
+ // Skip if already registered for this perspective instance
1920
+ if (__classPrivateFieldGet(this, _PerspectiveProxy_ensuredSubjectClasses, "f").has(className))
1921
+ return;
1883
1922
  // Note: Duplicate checking is handled on the Rust side in add_sdna
1884
1923
  // Generate SHACL SDNA (Prolog-free)
1885
1924
  if (!jsClass.generateSHACL) {
@@ -1892,6 +1931,14 @@ export class PerspectiveProxy {
1892
1931
  // Pass SHACL JSON to backend (Prolog-free)
1893
1932
  // Backend stores SHACL links directly
1894
1933
  await this.addSdna(className, '', 'subject_class', shaclJson);
1934
+ // Mark as registered for this perspective instance
1935
+ __classPrivateFieldGet(this, _PerspectiveProxy_ensuredSubjectClasses, "f").add(className);
1936
+ }
1937
+ /** Clear the per-instance ensured subject class cache.
1938
+ * Call this after wiping a perspective's links so that
1939
+ * subsequent register() calls re-add SHACL definitions. */
1940
+ clearEnsuredSubjectClasses() {
1941
+ __classPrivateFieldGet(this, _PerspectiveProxy_ensuredSubjectClasses, "f").clear();
1895
1942
  }
1896
1943
  getNeighbourhoodProxy() {
1897
1944
  return __classPrivateFieldGet(this, _PerspectiveProxy_client, "f").getNeighbourhoodProxy(__classPrivateFieldGet(this, _PerspectiveProxy_handle, "f").uuid);
@@ -1961,7 +2008,7 @@ export class PerspectiveProxy {
1961
2008
  return subscriptionProxy;
1962
2009
  }
1963
2010
  /**
1964
- * Creates a subscription for a SurrealQL query that updates in real-time.
2011
+ * Creates a subscription for a SPARQL query that updates in real-time.
1965
2012
  *
1966
2013
  * This method:
1967
2014
  * 1. Creates the subscription on the Rust side
@@ -1976,12 +2023,12 @@ export class PerspectiveProxy {
1976
2023
  * when dispose() is called. Make sure to call dispose() when you're done to
1977
2024
  * prevent memory leaks and ensure proper cleanup of resources.
1978
2025
  *
1979
- * @param query - SurrealQL query string
2026
+ /** Subscribe to a query with live updates via the SPARQL subscription endpoint.
2027
+ * @param query - Query string
1980
2028
  * @returns Initialized QuerySubscriptionProxy instance
1981
2029
  */
1982
- async subscribeSurrealDB(query) {
2030
+ async subscribeQuery(query) {
1983
2031
  const subscriptionProxy = new QuerySubscriptionProxy(this.uuid, query, __classPrivateFieldGet(this, _PerspectiveProxy_client, "f"));
1984
- subscriptionProxy.isSurrealDB = true;
1985
2032
  // Start the subscription on the Rust side first to get the real subscription ID
1986
2033
  await subscriptionProxy.subscribe();
1987
2034
  // Wait for the initial result
@@ -1989,4 +2036,4 @@ export class PerspectiveProxy {
1989
2036
  return subscriptionProxy;
1990
2037
  }
1991
2038
  }
1992
- _PerspectiveProxy_handle = new WeakMap(), _PerspectiveProxy_client = new WeakMap(), _PerspectiveProxy_perspectiveLinkAddedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkRemovedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkUpdatedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveSyncStateChangeCallbacks = new WeakMap();
2039
+ _PerspectiveProxy_handle = new WeakMap(), _PerspectiveProxy_client = new WeakMap(), _PerspectiveProxy_perspectiveLinkAddedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkRemovedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveLinkUpdatedCallbacks = new WeakMap(), _PerspectiveProxy_perspectiveSyncStateChangeCallbacks = new WeakMap(), _PerspectiveProxy_ensuredSubjectClasses = new WeakMap();