@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
@@ -7,8 +7,8 @@
7
7
  * decorators.ts stays focused on decorator registration logic.
8
8
  */
9
9
  import { SHACLShape } from "../shacl/SHACLShape";
10
- import { escapeSurrealString } from "../utils";
11
- import { compileWhereClause } from "./surreal-utils";
10
+ import { escapeQueryString } from "../utils";
11
+ import { compileWhereClause } from "./query-utils";
12
12
  import { propertyNameToSetterName } from "./util";
13
13
  /**
14
14
  * Build a SHACL shape for a model class.
@@ -131,7 +131,7 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
131
131
  // ── Constructor / Destructor entries ────────────────────────────
132
132
  const effectiveInitial = propMeta.initial
133
133
  ?? (propMeta.required && propMeta.writable && !propMeta.flag && propMeta.through
134
- ? "literal://string:" : undefined);
134
+ ? "literal:string:" : undefined);
135
135
  if (effectiveInitial) {
136
136
  constructorActions.push({
137
137
  action: "addLink",
@@ -182,7 +182,7 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
182
182
  // ── Build Getter (conformance filter) ───────────────────────────
183
183
  // Priority chain:
184
184
  // 1. Explicit getter string → use verbatim
185
- // 2. `where` clause → compile DSL to SurrealQL getter
185
+ // 2. `where` clause → compile DSL to SPARQL getter
186
186
  // 3. target + filter !== false → auto-derive from shape
187
187
  if (relMeta.getter) {
188
188
  relShape.getter = relMeta.getter;
@@ -195,8 +195,8 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
195
195
  : null;
196
196
  const conditions = compileWhereClause(relMeta.where, targetMetadata);
197
197
  if (conditions.length > 0) {
198
- const escapedPredicate = escapeSurrealString(relMeta.predicate);
199
- relShape.getter = `(->link[WHERE predicate = '${escapedPredicate}'].out[WHERE ${conditions.join(' AND ')}].uri)`;
198
+ const escapedPredicate = escapeQueryString(relMeta.predicate);
199
+ relShape.getter = `SELECT ?target WHERE { <Base> <${escapedPredicate}> ?target . ${conditions.join(' ')} }`;
200
200
  }
201
201
  }
202
202
  catch (e) {
@@ -204,18 +204,42 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
204
204
  }
205
205
  }
206
206
  else if (relMeta.target && relMeta.filter !== false) {
207
- try {
208
- const TargetClass = relMeta.target();
209
- const filter = conformanceFilterFn(relMeta.predicate, TargetClass);
210
- if (filter) {
211
- relShape.getter = filter.getter;
212
- relShape.conformanceConditions = filter.conformanceConditions;
207
+ // Lazy conformance filter: store deferred reference,
208
+ // resolve on first access via a getter on relShape
209
+ const targetThunk = relMeta.target;
210
+ const predicate = relMeta.predicate;
211
+ let resolved = false;
212
+ let cachedGetter;
213
+ let cachedConditions;
214
+ const resolveFilter = () => {
215
+ if (resolved)
216
+ return;
217
+ resolved = true;
218
+ try {
219
+ const TargetClass = targetThunk();
220
+ const filter = conformanceFilterFn(predicate, TargetClass);
221
+ if (filter) {
222
+ cachedGetter = filter.getter;
223
+ cachedConditions = filter.conformanceConditions;
224
+ }
213
225
  }
214
- }
215
- catch (e) {
216
- // Target class may not be available yet — getter will be
217
- // absent and runtime will fall back to unfiltered get_links
218
- }
226
+ catch (e) {
227
+ // Target class may not be available yet
228
+ }
229
+ };
230
+ // Define lazy getters that resolve on first access
231
+ Object.defineProperty(relShape, 'getter', {
232
+ get() { resolveFilter(); return cachedGetter; },
233
+ set(v) { resolved = true; cachedGetter = v; },
234
+ enumerable: true,
235
+ configurable: true,
236
+ });
237
+ Object.defineProperty(relShape, 'conformanceConditions', {
238
+ get() { resolveFilter(); return cachedConditions; },
239
+ set(v) { resolved = true; cachedConditions = v; },
240
+ enumerable: true,
241
+ configurable: true,
242
+ });
219
243
  }
220
244
  // ── sh:class — target shape reference ───────────────────────────
221
245
  if (relMeta.target) {
@@ -233,7 +257,7 @@ export function buildSHACL(subjectName, target, properties, allRelationsMeta, co
233
257
  shape.addProperty(relShape);
234
258
  }
235
259
  // Always set constructor and destructor actions on the shape, even
236
- // when empty. An empty array serialises to `literal://string:[]`
260
+ // when empty. An empty array serialises to `literal:string:[]`
237
261
  // which the Rust executor parses as a valid (no-op) command list,
238
262
  // avoiding "No SHACL constructor found" errors for models whose
239
263
  // properties are all optional and have no @Flag.
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Subscription Pool — deduplicates identical SPARQL subscriptions.
3
+ *
4
+ * When multiple UI components subscribe to the same SPARQL query on the same
5
+ * perspective, the pool shares a single `subscribeQuery()` call and distributes
6
+ * results to all registered callbacks. Hydration happens once per result set,
7
+ * then is shared across all subscribers.
8
+ *
9
+ * Key: `perspectiveUUID + sparqlQuery`
10
+ */
11
+ import type { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
12
+ type HydrateCallback = (rawResult: any) => Promise<any>;
13
+ type ResultCallback = (hydratedResult: any) => void;
14
+ export interface PooledSubscription {
15
+ /** The initial (hydrated) result */
16
+ initialResult: any;
17
+ /** Unsubscribe this particular callback from the pool */
18
+ dispose: () => void;
19
+ }
20
+ /**
21
+ * Subscribe to a SPARQL query, sharing the underlying subscription
22
+ * with any other subscribers using the same perspective + query.
23
+ *
24
+ * @param perspective - The perspective proxy
25
+ * @param sparqlQuery - The SPARQL query text
26
+ * @param hydrate - Async function that takes raw SPARQL results and returns hydrated results
27
+ * @param onResult - Callback for subsequent result updates (hydrated)
28
+ * @returns PooledSubscription with initial result and dispose function
29
+ */
30
+ export declare function pooledSubscribe(perspective: PerspectiveProxy, sparqlQuery: string, hydrate: HydrateCallback, onResult: ResultCallback): Promise<PooledSubscription>;
31
+ /**
32
+ * Clear the entire pool (for testing).
33
+ */
34
+ export declare function clearSubscriptionPool(): void;
35
+ /**
36
+ * Get the current pool size (for testing).
37
+ */
38
+ export declare function subscriptionPoolSize(): number;
39
+ export {};
@@ -0,0 +1,119 @@
1
+ /**
2
+ * Subscription Pool — deduplicates identical SPARQL subscriptions.
3
+ *
4
+ * When multiple UI components subscribe to the same SPARQL query on the same
5
+ * perspective, the pool shares a single `subscribeQuery()` call and distributes
6
+ * results to all registered callbacks. Hydration happens once per result set,
7
+ * then is shared across all subscribers.
8
+ *
9
+ * Key: `perspectiveUUID + sparqlQuery`
10
+ */
11
+ const pool = new Map();
12
+ function makeKey(perspectiveUUID, sparqlQuery) {
13
+ return `${perspectiveUUID}::${sparqlQuery}`;
14
+ }
15
+ /**
16
+ * Subscribe to a SPARQL query, sharing the underlying subscription
17
+ * with any other subscribers using the same perspective + query.
18
+ *
19
+ * @param perspective - The perspective proxy
20
+ * @param sparqlQuery - The SPARQL query text
21
+ * @param hydrate - Async function that takes raw SPARQL results and returns hydrated results
22
+ * @param onResult - Callback for subsequent result updates (hydrated)
23
+ * @returns PooledSubscription with initial result and dispose function
24
+ */
25
+ export async function pooledSubscribe(perspective, sparqlQuery, hydrate, onResult) {
26
+ const uuid = perspective.uuid || perspective.handle?.uuid || '';
27
+ const key = makeKey(uuid, sparqlQuery);
28
+ const entry = pool.get(key);
29
+ const subscriber = { onResult, hydrate };
30
+ if (entry) {
31
+ // Join existing subscription
32
+ entry.callbacks.add(subscriber);
33
+ entry.refCount++;
34
+ // Hydrate latest result for this new subscriber
35
+ let initialResult;
36
+ if (entry.latestHydrated !== undefined) {
37
+ initialResult = entry.latestHydrated;
38
+ }
39
+ else if (entry.latestRaw !== undefined) {
40
+ initialResult = await hydrate(entry.latestRaw);
41
+ }
42
+ return {
43
+ initialResult,
44
+ dispose: () => disposeSubscriber(key, subscriber),
45
+ };
46
+ }
47
+ // Create new subscription
48
+ const subscription = await perspective.subscribeQuery(sparqlQuery);
49
+ const newEntry = {
50
+ subscription,
51
+ callbacks: new Set([subscriber]),
52
+ latestRaw: subscription.result,
53
+ latestHydrated: undefined,
54
+ hydrating: false,
55
+ refCount: 1,
56
+ };
57
+ pool.set(key, newEntry);
58
+ // Set up shared result handler
59
+ subscription.onResult(async (rawResult) => {
60
+ newEntry.latestRaw = rawResult;
61
+ newEntry.hydrating = true;
62
+ try {
63
+ // Hydrate ONCE using the first subscriber's hydrate function
64
+ const firstSub = newEntry.callbacks.values().next().value;
65
+ if (firstSub) {
66
+ const hydrated = await firstSub.hydrate(rawResult);
67
+ newEntry.latestHydrated = hydrated;
68
+ // Distribute to all callbacks
69
+ for (const cb of newEntry.callbacks) {
70
+ try {
71
+ cb.onResult(hydrated);
72
+ }
73
+ catch (e) { /* subscriber error */ }
74
+ }
75
+ }
76
+ }
77
+ finally {
78
+ newEntry.hydrating = false;
79
+ }
80
+ });
81
+ // Hydrate initial result
82
+ const initialResult = await hydrate(subscription.result);
83
+ newEntry.latestHydrated = initialResult;
84
+ return {
85
+ initialResult,
86
+ dispose: () => disposeSubscriber(key, subscriber),
87
+ };
88
+ }
89
+ function disposeSubscriber(key, subscriber) {
90
+ const entry = pool.get(key);
91
+ if (!entry)
92
+ return;
93
+ entry.callbacks.delete(subscriber);
94
+ entry.refCount--;
95
+ if (entry.refCount <= 0) {
96
+ // Last subscriber — tear down the underlying subscription
97
+ if (entry.subscription?.dispose) {
98
+ entry.subscription.dispose();
99
+ }
100
+ pool.delete(key);
101
+ }
102
+ }
103
+ /**
104
+ * Clear the entire pool (for testing).
105
+ */
106
+ export function clearSubscriptionPool() {
107
+ for (const entry of pool.values()) {
108
+ if (entry.subscription?.dispose) {
109
+ entry.subscription.dispose();
110
+ }
111
+ }
112
+ pool.clear();
113
+ }
114
+ /**
115
+ * Get the current pool size (for testing).
116
+ */
117
+ export function subscriptionPoolSize() {
118
+ return pool.size;
119
+ }
@@ -2,7 +2,7 @@
2
2
  * Shared type definitions for the Ad4mModel system.
3
3
  *
4
4
  * Extracted into a standalone module so that utility files
5
- * (`surreal-utils.ts`, `decorators.ts`, etc.) can import types without
5
+ * (`query-utils.ts`, `decorators.ts`, etc.) can import types without
6
6
  * creating circular runtime dependencies on `Ad4mModel.ts`.
7
7
  */
8
8
  import type { Ad4mModel } from "./Ad4mModel";
@@ -128,7 +128,7 @@ export interface PropertyMetadata {
128
128
  prologGetter?: string;
129
129
  /** Custom Prolog setter code */
130
130
  prologSetter?: string;
131
- /** Custom SurrealQL getter code */
131
+ /** Custom getter code */
132
132
  getter?: string;
133
133
  /** Whether stored locally only */
134
134
  local?: boolean;
@@ -145,7 +145,7 @@ export interface RelationMetadata {
145
145
  name: string;
146
146
  /** The predicate URI (through value) */
147
147
  predicate: string;
148
- /** Custom SurrealQL getter code */
148
+ /** Custom getter code */
149
149
  getter?: string;
150
150
  /** Whether stored locally only */
151
151
  local?: boolean;
@@ -2,7 +2,7 @@
2
2
  * Shared type definitions for the Ad4mModel system.
3
3
  *
4
4
  * Extracted into a standalone module so that utility files
5
- * (`surreal-utils.ts`, `decorators.ts`, etc.) can import types without
5
+ * (`query-utils.ts`, `decorators.ts`, etc.) can import types without
6
6
  * creating circular runtime dependencies on `Ad4mModel.ts`.
7
7
  */
8
8
  export {};
@@ -27,28 +27,12 @@ export declare class PerspectiveClient {
27
27
  publishSnapshotByUUID(uuid: string): Promise<string | null>;
28
28
  queryLinks(uuid: string, query: LinkQuery): Promise<LinkExpression[]>;
29
29
  queryProlog(uuid: string, query: string): Promise<any>;
30
- /**
31
- * Executes a read-only SurrealQL query against a perspective's link cache.
32
- *
33
- * Security: Only SELECT, RETURN, and other read-only queries are permitted.
34
- * Mutating operations (DELETE, UPDATE, INSERT, etc.) are blocked.
35
- *
36
- * Note: GraphQL field name is "perspectiveQuerySurrealDb" (lowercase "b" in "Db")
37
- * as generated from Rust method "perspective_query_surreal_db"
38
- */
39
- querySurrealDB(uuid: string, query: string): Promise<any>;
30
+ querySparql(uuid: string, query: string): Promise<any>;
40
31
  subscribeQuery(uuid: string, query: string): Promise<{
41
32
  subscriptionId: string;
42
33
  result: AllInstancesResult;
43
34
  isInit?: boolean;
44
35
  }>;
45
- perspectiveSubscribeSurrealQuery(uuid: string, query: string): Promise<{
46
- subscriptionId: string;
47
- result: AllInstancesResult;
48
- isInit?: boolean;
49
- }>;
50
- perspectiveKeepAliveSurrealQuery(uuid: string, subscriptionId: string): Promise<boolean>;
51
- perspectiveDisposeSurrealQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
52
36
  subscribeToQueryUpdates(subscriptionId: string, onData: (result: AllInstancesResult) => void): () => void;
53
37
  keepAliveQuery(uuid: string, subscriptionId: string): Promise<boolean>;
54
38
  disposeQuerySubscription(uuid: string, subscriptionId: string): Promise<boolean>;
@@ -139,23 +139,14 @@ export class PerspectiveClient {
139
139
  }));
140
140
  return JSON.parse(perspectiveQueryProlog);
141
141
  }
142
- /**
143
- * Executes a read-only SurrealQL query against a perspective's link cache.
144
- *
145
- * Security: Only SELECT, RETURN, and other read-only queries are permitted.
146
- * Mutating operations (DELETE, UPDATE, INSERT, etc.) are blocked.
147
- *
148
- * Note: GraphQL field name is "perspectiveQuerySurrealDb" (lowercase "b" in "Db")
149
- * as generated from Rust method "perspective_query_surreal_db"
150
- */
151
- async querySurrealDB(uuid, query) {
152
- const { perspectiveQuerySurrealDb } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").query({
153
- query: gql `query perspectiveQuerySurrealDb($uuid: String!, $query: String!) {
154
- perspectiveQuerySurrealDb(uuid: $uuid, query: $query)
142
+ async querySparql(uuid, query) {
143
+ const { perspectiveQuerySparql } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").query({
144
+ query: gql `query perspectiveQuerySparql($uuid: String!, $query: String!) {
145
+ perspectiveQuerySparql(uuid: $uuid, query: $query)
155
146
  }`,
156
147
  variables: { uuid, query }
157
148
  }));
158
- return JSON.parse(perspectiveQuerySurrealDb);
149
+ return JSON.parse(perspectiveQuerySparql);
159
150
  }
160
151
  async subscribeQuery(uuid, query) {
161
152
  const { perspectiveSubscribeQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
@@ -182,49 +173,6 @@ export class PerspectiveClient {
182
173
  }
183
174
  return { subscriptionId, result: finalResult, isInit };
184
175
  }
185
- async perspectiveSubscribeSurrealQuery(uuid, query) {
186
- const { perspectiveSubscribeSurrealQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
187
- mutation: gql `mutation perspectiveSubscribeSurrealQuery($uuid: String!, $query: String!) {
188
- perspectiveSubscribeSurrealQuery(uuid: $uuid, query: $query) {
189
- subscriptionId
190
- result
191
- }
192
- }`,
193
- variables: { uuid, query }
194
- }));
195
- const { subscriptionId, result } = perspectiveSubscribeSurrealQuery;
196
- let finalResult = result;
197
- let isInit = false;
198
- if (finalResult.startsWith("#init#")) {
199
- finalResult = finalResult.substring(6);
200
- isInit = true;
201
- }
202
- try {
203
- finalResult = JSON.parse(finalResult);
204
- }
205
- catch (e) {
206
- console.error('Error parsing perspectiveSubscribeSurrealQuery result:', e);
207
- }
208
- return { subscriptionId, result: finalResult, isInit };
209
- }
210
- async perspectiveKeepAliveSurrealQuery(uuid, subscriptionId) {
211
- const { perspectiveKeepAliveSurrealQuery } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
212
- mutation: gql `mutation perspectiveKeepAliveSurrealQuery($uuid: String!, $subscriptionId: String!) {
213
- perspectiveKeepAliveSurrealQuery(uuid: $uuid, subscriptionId: $subscriptionId)
214
- }`,
215
- variables: { uuid, subscriptionId }
216
- }));
217
- return perspectiveKeepAliveSurrealQuery;
218
- }
219
- async perspectiveDisposeSurrealQuerySubscription(uuid, subscriptionId) {
220
- const { perspectiveDisposeSurrealQuerySubscription } = unwrapApolloResult(await __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").mutate({
221
- mutation: gql `mutation perspectiveDisposeSurrealQuerySubscription($uuid: String!, $subscriptionId: String!) {
222
- perspectiveDisposeSurrealQuerySubscription(uuid: $uuid, subscriptionId: $subscriptionId)
223
- }`,
224
- variables: { uuid, subscriptionId }
225
- }));
226
- return perspectiveDisposeSurrealQuerySubscription;
227
- }
228
176
  subscribeToQueryUpdates(subscriptionId, onData) {
229
177
  const subscription = __classPrivateFieldGet(this, _PerspectiveClient_apolloClient, "f").subscribe({
230
178
  query: gql `
@@ -46,7 +46,6 @@ type QueryCallback = (result: AllInstancesResult) => void;
46
46
  */
47
47
  export declare class QuerySubscriptionProxy {
48
48
  #private;
49
- isSurrealDB: boolean;
50
49
  /** Creates a new query subscription
51
50
  * @param uuid - The UUID of the perspective
52
51
  * @param query - The Prolog query to subscribe to
@@ -299,33 +298,22 @@ export declare class PerspectiveProxy {
299
298
  */
300
299
  infer(query: string): Promise<any>;
301
300
  /**
302
- * Executes a SurrealQL query against the perspective's link cache.
303
- * This allows powerful SQL-like queries on the link data stored in SurrealDB.
301
+ * Executes a SPARQL query against the perspective's link cache.
302
+ * This allows powerful SQL-like queries on the link data stored in SPARQL.
304
303
  *
305
304
  * **Security Note:** Only read-only queries (SELECT, RETURN, etc.) are permitted.
306
305
  * Mutating operations (DELETE, UPDATE, INSERT, CREATE, DROP, DEFINE, etc.) are
307
306
  * blocked for security reasons. Use the perspective's add/remove methods to modify links.
308
307
  *
309
- * @param query - SurrealQL query string (read-only operations only)
308
+ * @param query - SPARQL query string (read-only operations only)
310
309
  * @returns Query results as parsed JSON
311
310
  *
312
- * @example
313
- * ```typescript
314
- * // Get all links
315
- * const links = await perspective.querySurrealDB('SELECT * FROM link');
316
- *
317
- * // Filter links by predicate
318
- * const follows = await perspective.querySurrealDB(
319
- * "SELECT * FROM link WHERE predicate = 'follows'"
320
- * );
321
- *
322
- * // Complex aggregation query
323
- * const stats = await perspective.querySurrealDB(
324
- * "SELECT predicate, count() as total FROM link GROUP BY predicate"
325
- * );
326
- * ```
311
+ * Executes a SPARQL query against the perspective's RDF (Oxigraph) store.
312
+ *
313
+ * @param query - SPARQL query string
314
+ * @returns Query results as parsed JSON
327
315
  */
328
- querySurrealDB(query: string): Promise<any>;
316
+ querySparql(query: string): Promise<any>;
329
317
  /**
330
318
  * Adds a new link to the perspective.
331
319
  *
@@ -552,6 +540,11 @@ export declare class PerspectiveProxy {
552
540
  * await perspective.addSdna('Recipe', prologCode, 'subject_class');
553
541
  */
554
542
  addSdna(name: string, sdnaCode: string, sdnaType: "subject_class" | "flow" | "custom", shaclJson?: string): Promise<boolean>;
543
+ /**
544
+ * Adds a subject class to the perspective.
545
+ * Alias for addSdna() with sdnaType='subject_class'.
546
+ */
547
+ addSubjectClass(name: string, shaclJson: string): Promise<boolean>;
555
548
  /**
556
549
  * **Recommended way to add SDNA schemas.**
557
550
  *
@@ -693,6 +686,23 @@ export declare class PerspectiveProxy {
693
686
  * Gets subject class metadata from SHACL links using SHACLShape.fromLinks().
694
687
  * Retrieves the SHACL shape and extracts metadata for instance queries.
695
688
  */
689
+ getSubjectClassMetadata(className: string): Promise<{
690
+ requiredPredicates: string[];
691
+ requiredTriples: Array<{
692
+ predicate: string;
693
+ target?: string;
694
+ }>;
695
+ properties: Map<string, {
696
+ predicate: string;
697
+ resolveLanguage?: string;
698
+ }>;
699
+ relations: Map<string, {
700
+ predicate: string;
701
+ instanceFilter?: string;
702
+ condition?: string;
703
+ }>;
704
+ } | null>;
705
+ /** @deprecated Use getSubjectClassMetadata() */
696
706
  getSubjectClassMetadataFromSDNA(className: string): Promise<{
697
707
  requiredPredicates: string[];
698
708
  requiredTriples: Array<{
@@ -710,22 +720,26 @@ export declare class PerspectiveProxy {
710
720
  }>;
711
721
  } | null>;
712
722
  /**
713
- * Generates a SurrealDB query to find instances based on class metadata.
723
+ * Generates a SPARQL query to find instances based on class metadata.
724
+ */
725
+ /**
726
+ * Finds all instances matching subject class metadata by querying links.
727
+ * Returns base URIs of matching instances.
714
728
  */
715
- private generateSurrealInstanceQuery;
729
+ private findInstancesByMetadata;
716
730
  /**
717
- * Gets a property value using SurrealDB when Prolog fails.
731
+ * Gets a property value using SPARQL when Prolog fails.
718
732
  * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
719
733
  */
720
- getPropertyValueViaSurreal(baseExpression: string, className: string, propertyName: string): Promise<any>;
734
+ getPropertyValueViaSparql(baseExpression: string, className: string, propertyName: string): Promise<any>;
721
735
  /**
722
- * Gets relation values using SurrealDB when Prolog fails.
736
+ * Gets relation values using SPARQL when Prolog fails.
723
737
  * This is used as a fallback in SdnaOnly mode where link data isn't in Prolog.
724
738
  * Note: This is used by Subject.ts (legacy pattern). Ad4mModel.ts uses getModelMetadata() instead.
725
739
  */
726
- getRelationValuesViaSurreal(baseExpression: string, className: string, relationName: string): Promise<any[]>;
740
+ getRelationValuesViaSparql(baseExpression: string, className: string, relationName: string): Promise<any[]>;
727
741
  /**
728
- * Batch-checks multiple expressions against subject class metadata using a single or limited SurrealDB queries.
742
+ * Batch-checks multiple expressions against subject class metadata using a single or limited SPARQL queries.
729
743
  * This avoids N+1 query problems by checking all values at once.
730
744
  */
731
745
  batchCheckSubjectInstances(expressions: string[], metadata: {
@@ -785,6 +799,12 @@ export declare class PerspectiveProxy {
785
799
  * static generateSDNA() function and adds it to the perspective's SDNA.
786
800
  */
787
801
  ensureSDNASubjectClass(jsClass: any): Promise<void>;
802
+ /** Takes a JS class (its constructor) and ensures the SHACL subject class exists. */
803
+ ensureSubjectClass(jsClass: any): Promise<void>;
804
+ /** Clear the per-instance ensured subject class cache.
805
+ * Call this after wiping a perspective's links so that
806
+ * subsequent register() calls re-add SHACL definitions. */
807
+ clearEnsuredSubjectClasses(): void;
788
808
  getNeighbourhoodProxy(): NeighbourhoodProxy;
789
809
  /**
790
810
  * Returns a proxy object for working with AI capabilities.
@@ -842,7 +862,7 @@ export declare class PerspectiveProxy {
842
862
  */
843
863
  subscribeInfer(query: string): Promise<QuerySubscriptionProxy>;
844
864
  /**
845
- * Creates a subscription for a SurrealQL query that updates in real-time.
865
+ * Creates a subscription for a SPARQL query that updates in real-time.
846
866
  *
847
867
  * This method:
848
868
  * 1. Creates the subscription on the Rust side
@@ -857,9 +877,10 @@ export declare class PerspectiveProxy {
857
877
  * when dispose() is called. Make sure to call dispose() when you're done to
858
878
  * prevent memory leaks and ensure proper cleanup of resources.
859
879
  *
860
- * @param query - SurrealQL query string
880
+ /** Subscribe to a query with live updates via the SPARQL subscription endpoint.
881
+ * @param query - Query string
861
882
  * @returns Initialized QuerySubscriptionProxy instance
862
883
  */
863
- subscribeSurrealDB(query: string): Promise<QuerySubscriptionProxy>;
884
+ subscribeQuery(query: string): Promise<QuerySubscriptionProxy>;
864
885
  }
865
886
  export {};