@coasys/ad4m 0.13.0-test-7 → 0.13.0-test-8-profile-cache-fix

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 (63) hide show
  1. package/lib/index.cjs +1121 -835
  2. package/lib/index.js +1108 -835
  3. package/lib/src/Ad4mClient.d.ts +4 -1
  4. package/lib/src/Ad4mClient.js +2 -2
  5. package/lib/src/agent/AgentClient.d.ts +3 -0
  6. package/lib/src/agent/AgentClient.js +27 -5
  7. package/lib/src/ai/AIClient.js +1 -1
  8. package/lib/src/apiClient.d.ts +5 -1
  9. package/lib/src/apiClient.js +14 -6
  10. package/lib/src/index.d.ts +4 -0
  11. package/lib/src/index.js +4 -0
  12. package/lib/src/model/Ad4mModel.d.ts +30 -36
  13. package/lib/src/model/Ad4mModel.js +93 -382
  14. package/lib/src/model/ModelQueryBuilder.d.ts +5 -10
  15. package/lib/src/model/ModelQueryBuilder.js +142 -62
  16. package/lib/src/model/decorators.d.ts +7 -4
  17. package/lib/src/model/decorators.js +0 -7
  18. package/lib/src/model/query-sparql.d.ts +0 -10
  19. package/lib/src/model/query-sparql.js +12 -17
  20. package/lib/src/model/shacl-gen.js +120 -47
  21. package/lib/src/model/types.d.ts +140 -4
  22. package/lib/src/perspectives/PerspectiveClient.d.ts +13 -4
  23. package/lib/src/perspectives/PerspectiveClient.js +22 -6
  24. package/lib/src/perspectives/PerspectiveProxy.d.ts +27 -7
  25. package/lib/src/perspectives/PerspectiveProxy.js +60 -12
  26. package/lib/src/perspectives/SparqlBindings.d.ts +47 -0
  27. package/lib/src/perspectives/SparqlBindings.js +65 -0
  28. package/lib/src/perspectives/WakerSubscriptionManager.js +5 -4
  29. package/lib/src/shacl/NodeExpression.d.ts +44 -0
  30. package/lib/src/shacl/NodeExpression.js +39 -0
  31. package/lib/src/shacl/SHACLShape.d.ts +23 -0
  32. package/lib/src/shacl/SHACLShape.js +115 -1
  33. package/lib/src/shacl/builders.d.ts +58 -0
  34. package/lib/src/shacl/builders.js +76 -0
  35. package/lib/src/shacl/index.d.ts +36 -0
  36. package/lib/src/shacl/index.js +33 -0
  37. package/package.json +1 -1
  38. package/src/Ad4mClient.ts +7 -2
  39. package/src/agent/AgentClient.ts +35 -7
  40. package/src/ai/AIClient.ts +1 -1
  41. package/src/apiClient.ts +17 -6
  42. package/src/index.ts +4 -0
  43. package/src/model/Ad4mModel.test.ts +274 -72
  44. package/src/model/Ad4mModel.ts +140 -420
  45. package/src/model/ModelQueryBuilder.ts +136 -71
  46. package/src/model/decorators.ts +7 -13
  47. package/src/model/query-sparql.test.ts +36 -20
  48. package/src/model/query-sparql.ts +12 -18
  49. package/src/model/relation-filtering.test.ts +46 -39
  50. package/src/model/shacl-gen.ts +128 -54
  51. package/src/model/shacl-roundtrip.test.ts +197 -0
  52. package/src/model/types-typed-query.test.ts +360 -0
  53. package/src/model/types.ts +196 -4
  54. package/src/perspectives/PerspectiveClient.ts +24 -8
  55. package/src/perspectives/PerspectiveProxy.test.ts +85 -1
  56. package/src/perspectives/PerspectiveProxy.ts +65 -20
  57. package/src/perspectives/SparqlBindings.ts +79 -0
  58. package/src/perspectives/WakerSubscriptionManager.ts +5 -4
  59. package/src/shacl/NodeExpression.ts +54 -0
  60. package/src/shacl/SHACLShape.test.ts +172 -0
  61. package/src/shacl/SHACLShape.ts +173 -1
  62. package/src/shacl/builders.ts +86 -0
  63. package/src/shacl/index.ts +72 -0
@@ -16,7 +16,10 @@ import { AIClient } from './ai/AIClient';
16
16
  */
17
17
  export declare class Ad4mClient {
18
18
  #private;
19
- constructor(baseUrl: string, token?: string, subscribe?: boolean);
19
+ constructor(baseUrl: string, token?: string, subscribe?: boolean, options?: {
20
+ webSocketImpl?: new (url: string) => WebSocket;
21
+ fetchImpl?: typeof fetch;
22
+ });
20
23
  get agent(): AgentClient;
21
24
  get expression(): ExpressionClient;
22
25
  get languages(): LanguageClient;
@@ -29,7 +29,7 @@ import { Ad4mModel } from './model/Ad4mModel';
29
29
  * for the respective functionality.
30
30
  */
31
31
  export class Ad4mClient {
32
- constructor(baseUrl, token, subscribe = true) {
32
+ constructor(baseUrl, token, subscribe = true, options) {
33
33
  _Ad4mClient_baseUrl.set(this, void 0);
34
34
  _Ad4mClient_token.set(this, void 0);
35
35
  _Ad4mClient_apiClient.set(this, void 0);
@@ -42,7 +42,7 @@ export class Ad4mClient {
42
42
  _Ad4mClient_aiClient.set(this, void 0);
43
43
  __classPrivateFieldSet(this, _Ad4mClient_baseUrl, baseUrl, "f");
44
44
  __classPrivateFieldSet(this, _Ad4mClient_token, token, "f");
45
- __classPrivateFieldSet(this, _Ad4mClient_apiClient, new ApiClient(baseUrl, token), "f");
45
+ __classPrivateFieldSet(this, _Ad4mClient_apiClient, new ApiClient(baseUrl, token, options?.webSocketImpl, options?.fetchImpl), "f");
46
46
  __classPrivateFieldSet(this, _Ad4mClient_agentClient, new AgentClient(baseUrl, token, subscribe, __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f")), "f");
47
47
  __classPrivateFieldSet(this, _Ad4mClient_expressionClient, new ExpressionClient(baseUrl, token, __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f")), "f");
48
48
  __classPrivateFieldSet(this, _Ad4mClient_languageClient, new LanguageClient(baseUrl, token, __classPrivateFieldGet(this, _Ad4mClient_apiClient, "f")), "f");
@@ -20,6 +20,9 @@ export declare class AgentClient {
20
20
  #private;
21
21
  /** TTL for remote (non-self) agent profiles in L1 cache (ms). */
22
22
  static REMOTE_AGENT_TTL_MS: number;
23
+ /** TTL for remote agent profiles in the L2 (IndexedDB) cache (ms).
24
+ * After this window any restart triggers a fresh network fetch. */
25
+ static REMOTE_AGENT_TTL_L2_MS: number;
23
26
  constructor(baseUrl: string, token?: string, subscribe?: boolean, sharedApiClient?: ApiClient);
24
27
  me(): Promise<Agent>;
25
28
  status(): Promise<AgentStatus>;
@@ -31,6 +31,7 @@ export class AgentClient {
31
31
  // L1: in-memory promise cache with timestamps for TTL
32
32
  _AgentClient_memCache.set(this, new Map());
33
33
  // L2: persistent cache (IndexedDB in browser, NullCache in Node)
34
+ // Entries are wrapped with a timestamp so the TTL can be enforced across restarts.
34
35
  _AgentClient_persistent.set(this, void 0);
35
36
  // Self-DID for event-driven invalidation (no TTL for own profile)
36
37
  _AgentClient_selfDid.set(this, null);
@@ -54,6 +55,11 @@ export class AgentClient {
54
55
  const agent = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.get');
55
56
  let agentObject = new Agent(agent.did, agent.perspective);
56
57
  agentObject.directMessageLanguage = agent.directMessageLanguage;
58
+ // Auto-set selfDid so event-driven cache invalidation works
59
+ // without requiring apps to call setSelfDid() manually
60
+ if (agentObject.did && !__classPrivateFieldGet(this, _AgentClient_selfDid, "f")) {
61
+ __classPrivateFieldSet(this, _AgentClient_selfDid, agentObject.did, "f");
62
+ }
57
63
  return agentObject;
58
64
  }
59
65
  async status() {
@@ -90,13 +96,14 @@ export class AgentClient {
90
96
  // Deduplicate: store the promise immediately so concurrent calls share one RPC
91
97
  const promise = (async () => {
92
98
  // L2: check persistent cache before network
93
- const persisted = await __classPrivateFieldGet(this, _AgentClient_persistent, "f").get(did);
94
- if (persisted) {
95
- return persisted;
99
+ const entry = await __classPrivateFieldGet(this, _AgentClient_persistent, "f").get(did);
100
+ // entry.agent may be undefined for pre-TTL cache entries (migration) — treat as expired
101
+ if (entry?.agent && (now - (entry.ts ?? 0)) < AgentClient.REMOTE_AGENT_TTL_L2_MS) {
102
+ return entry.agent;
96
103
  }
97
104
  // L3: network fetch
98
105
  const result = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.byDid', { did });
99
- __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(did, result); // fire-and-forget write to L2
106
+ __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(did, { agent: result, ts: Date.now() }); // fire-and-forget write to L2
100
107
  return result;
101
108
  })();
102
109
  __classPrivateFieldGet(this, _AgentClient_memCache, "f").set(did, { promise, ts: now });
@@ -141,6 +148,12 @@ export class AgentClient {
141
148
  const a = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.updateProfile', { publicPerspective: cleanedPerspective });
142
149
  const agent = new Agent(a.did, a.perspective);
143
150
  agent.directMessageLanguage = a.directMessageLanguage;
151
+ // Immediately update byDID cache so subsequent byDID() calls
152
+ // return fresh data without waiting for the subscription event
153
+ if (agent.did) {
154
+ __classPrivateFieldGet(this, _AgentClient_memCache, "f").set(agent.did, { promise: Promise.resolve(agent), ts: Date.now() });
155
+ __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, { agent, ts: Date.now() }); // fire-and-forget
156
+ }
144
157
  return agent;
145
158
  }
146
159
  async mutatePublicPerspective(mutations) {
@@ -165,6 +178,12 @@ export class AgentClient {
165
178
  const a = await __classPrivateFieldGet(this, _AgentClient_apiClient, "f").call('agent.updateProfile', { dmLanguage: directMessageLanguage });
166
179
  const agent = new Agent(a.did, a.perspective);
167
180
  agent.directMessageLanguage = a.directMessageLanguage;
181
+ // Immediately update byDID cache so subsequent byDID() calls
182
+ // return fresh data without waiting for the subscription event
183
+ if (agent.did) {
184
+ __classPrivateFieldGet(this, _AgentClient_memCache, "f").set(agent.did, { promise: Promise.resolve(agent), ts: Date.now() });
185
+ __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, { agent, ts: Date.now() }); // fire-and-forget
186
+ }
168
187
  return agent;
169
188
  }
170
189
  async addEntanglementProofs(proofs) {
@@ -195,7 +214,7 @@ export class AgentClient {
195
214
  promise: Promise.resolve(agent),
196
215
  ts: Date.now(),
197
216
  });
198
- __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, agent); // fire-and-forget
217
+ __classPrivateFieldGet(this, _AgentClient_persistent, "f").put(agent.did, { agent, ts: Date.now() }); // fire-and-forget
199
218
  }
200
219
  __classPrivateFieldGet(this, _AgentClient_updatedCallbacks, "f").forEach((cb) => cb(agent));
201
220
  }
@@ -299,3 +318,6 @@ export class AgentClient {
299
318
  _AgentClient_apiClient = new WeakMap(), _AgentClient_baseUrl = new WeakMap(), _AgentClient_token = new WeakMap(), _AgentClient_appsChangedCallback = new WeakMap(), _AgentClient_updatedCallbacks = new WeakMap(), _AgentClient_agentStatusChangedCallbacks = new WeakMap(), _AgentClient_hostingUserInfoChangedCallbacks = new WeakMap(), _AgentClient_computeLogUpdatedCallbacks = new WeakMap(), _AgentClient_unsubscribers = new WeakMap(), _AgentClient_memCache = new WeakMap(), _AgentClient_persistent = new WeakMap(), _AgentClient_selfDid = new WeakMap();
300
319
  /** TTL for remote (non-self) agent profiles in L1 cache (ms). */
301
320
  AgentClient.REMOTE_AGENT_TTL_MS = 5 * 60000; // 5 minutes
321
+ /** TTL for remote agent profiles in the L2 (IndexedDB) cache (ms).
322
+ * After this window any restart triggers a fresh network fetch. */
323
+ AgentClient.REMOTE_AGENT_TTL_L2_MS = 5 * 60000; // 5 minutes
@@ -120,7 +120,7 @@ export class AIClient {
120
120
  // Use slice to get only the relevant portion of the underlying ArrayBuffer
121
121
  // (Float32Array may be a view over a larger buffer)
122
122
  const bodyBuffer = typedAudio.buffer.slice(typedAudio.byteOffset, typedAudio.byteOffset + typedAudio.byteLength);
123
- const response = await fetch(`${baseUrl}/api/v1/ai/transcription/feed`, {
123
+ const response = await __classPrivateFieldGet(this, _AIClient_apiClient, "f").doFetch(`${baseUrl}/api/v1/ai/transcription/feed`, {
124
124
  method: 'POST',
125
125
  headers: {
126
126
  'Content-Type': 'application/octet-stream',
@@ -14,9 +14,13 @@ export declare class RpcError extends Error {
14
14
  export declare class ApiClient {
15
15
  private baseUrl;
16
16
  private token?;
17
- constructor(baseUrl: string, token?: string);
17
+ private readonly _webSocketImpl?;
18
+ private readonly _fetchImpl?;
19
+ constructor(baseUrl: string, token?: string, webSocketImpl?: new (url: string) => WebSocket, fetchImpl?: typeof fetch);
18
20
  getBaseUrl(): string;
19
21
  getToken(): string | undefined;
22
+ /** Perform an HTTP request, using an injected fetch implementation if provided. */
23
+ doFetch(url: string, init: RequestInit): Promise<Response>;
20
24
  setToken(token: string): void;
21
25
  private _ws;
22
26
  private _wsCallbacks;
@@ -19,7 +19,7 @@ function nextId() {
19
19
  return String(++_idCounter);
20
20
  }
21
21
  export class ApiClient {
22
- constructor(baseUrl, token) {
22
+ constructor(baseUrl, token, webSocketImpl, fetchImpl) {
23
23
  // ── WebSocket RPC core ──────────────────────────────────────────────────
24
24
  this._ws = null;
25
25
  this._wsCallbacks = new Set();
@@ -32,9 +32,15 @@ export class ApiClient {
32
32
  this._wsPingTimer = null;
33
33
  this.baseUrl = baseUrl;
34
34
  this.token = token;
35
+ this._webSocketImpl = webSocketImpl;
36
+ this._fetchImpl = fetchImpl;
35
37
  }
36
38
  getBaseUrl() { return this.baseUrl; }
37
39
  getToken() { return this.token; }
40
+ /** Perform an HTTP request, using an injected fetch implementation if provided. */
41
+ doFetch(url, init) {
42
+ return this._fetchImpl ? this._fetchImpl(url, init) : fetch(url, init);
43
+ }
38
44
  setToken(token) {
39
45
  this.token = token;
40
46
  }
@@ -47,7 +53,7 @@ export class ApiClient {
47
53
  return tokenParam ? `${wsBase}${path}?${tokenParam}` : `${wsBase}${path}`;
48
54
  }
49
55
  _ensureWs() {
50
- if (this._ws && (this._ws.readyState === WebSocket.OPEN || this._ws.readyState === WebSocket.CONNECTING)) {
56
+ if (this._ws && (this._ws.readyState === 1 /* OPEN */ || this._ws.readyState === 0 /* CONNECTING */)) {
51
57
  return;
52
58
  }
53
59
  // Prevent duplicate connections from concurrent callers
@@ -58,7 +64,8 @@ export class ApiClient {
58
64
  this._wsReadyResolve = resolve;
59
65
  });
60
66
  const url = this._getWsUrl();
61
- const ws = new WebSocket(url);
67
+ const WsImpl = this._webSocketImpl ?? WebSocket;
68
+ const ws = new WsImpl(url);
62
69
  this._ws = ws;
63
70
  ws.onopen = () => {
64
71
  this._wsReconnectDelay = INITIAL_RECONNECT_DELAY_MS;
@@ -108,12 +115,13 @@ export class ApiClient {
108
115
  // Reset the readiness promise so future calls reconnect
109
116
  this._wsReady = null;
110
117
  // Reject all pending calls
118
+ const hadPendingCalls = this._pendingCalls.size > 0;
111
119
  for (const [id, pending] of this._pendingCalls) {
112
120
  clearTimeout(pending.timer);
113
121
  pending.reject(new RpcError(503, 'WebSocket connection closed'));
114
122
  }
115
123
  this._pendingCalls.clear();
116
- if (!this._wsClosed && (this._wsCallbacks.size > 0 || this._pendingCalls.size > 0)) {
124
+ if (!this._wsClosed && (this._wsCallbacks.size > 0 || hadPendingCalls)) {
117
125
  this._scheduleReconnect();
118
126
  }
119
127
  };
@@ -121,7 +129,7 @@ export class ApiClient {
121
129
  _startPing() {
122
130
  this._stopPing();
123
131
  this._wsPingTimer = setInterval(() => {
124
- if (this._ws && this._ws.readyState === WebSocket.OPEN) {
132
+ if (this._ws && this._ws.readyState === 1 /* OPEN */) {
125
133
  this._ws.send(JSON.stringify({ type: 'ping' }));
126
134
  }
127
135
  }, 30000);
@@ -174,7 +182,7 @@ export class ApiClient {
174
182
  reject,
175
183
  timer,
176
184
  });
177
- if (this._ws && this._ws.readyState === WebSocket.OPEN) {
185
+ if (this._ws && this._ws.readyState === 1 /* OPEN */) {
178
186
  this._ws.send(JSON.stringify(message));
179
187
  }
180
188
  else {
@@ -16,6 +16,7 @@ export * from "./Literal";
16
16
  export * from "./perspectives/Perspective";
17
17
  export * from "./perspectives/PerspectiveHandle";
18
18
  export * from "./perspectives/PerspectiveProxy";
19
+ export * from "./perspectives/SparqlBindings";
19
20
  export * from "./perspectives/WakerSubscriptionManager";
20
21
  export * from "./perspectives/PerspectiveDiff";
21
22
  export * from "./perspectives/LinkQuery";
@@ -33,6 +34,9 @@ export * from "./runtime/RuntimeTypes";
33
34
  export { Model as AIModel, ModelApi, TokenizerSource, LocalModel, ModelType, ModelApiInput, TokenizerSourceInput, LocalModelInput, ModelInput, VoiceActivityParamsInput } from "./ai/AITypes";
34
35
  export * from './shacl/SHACLShape';
35
36
  export { SHACLFlow, FlowState, FlowTransition, LinkPattern, FlowableCondition } from './shacl/SHACLFlow';
37
+ export * from './shacl/NodeExpression';
38
+ export * from './shacl/builders';
39
+ export { fileToDataUri } from './shacl/index';
36
40
  export * from "./generated/api";
37
41
  export { RpcError } from "./apiClient";
38
42
  /** @deprecated Use `RpcError` instead. */
package/lib/src/index.js CHANGED
@@ -16,6 +16,7 @@ export * from "./Literal";
16
16
  export * from "./perspectives/Perspective";
17
17
  export * from "./perspectives/PerspectiveHandle";
18
18
  export * from "./perspectives/PerspectiveProxy";
19
+ export * from "./perspectives/SparqlBindings";
19
20
  export * from "./perspectives/WakerSubscriptionManager";
20
21
  export * from "./perspectives/PerspectiveDiff";
21
22
  export * from "./perspectives/LinkQuery";
@@ -33,6 +34,9 @@ export * from "./runtime/RuntimeTypes";
33
34
  export { Model as AIModel, ModelApi, TokenizerSource, LocalModel, ModelApiInput, TokenizerSourceInput, LocalModelInput, ModelInput, VoiceActivityParamsInput } from "./ai/AITypes";
34
35
  export * from './shacl/SHACLShape';
35
36
  export { SHACLFlow } from './shacl/SHACLFlow';
37
+ export * from './shacl/NodeExpression';
38
+ export * from './shacl/builders';
39
+ export { fileToDataUri } from './shacl/index';
36
40
  export * from "./generated/api";
37
41
  export { RpcError } from "./apiClient";
38
42
  /** @deprecated Use `RpcError` instead. */
@@ -2,7 +2,7 @@ import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
2
2
  import type { SHACLShape } from "../shacl/SHACLShape";
3
3
  import type { JSONSchema, JSONSchemaToModelOptions } from "./json-schema";
4
4
  import { ModelQueryBuilder } from "./ModelQueryBuilder";
5
- import type { ParentScope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata } from "./types";
5
+ import type { ParentScope, IncludeMap, Query, GetOptions, ResultsWithTotalCount, PaginationResult, ModelMetadata, TypedQuery, IncludeExtras, IncludeOf } from "./types";
6
6
  /**
7
7
  * Base class for defining data models in AD4M.
8
8
  *
@@ -229,7 +229,8 @@ export declare class Ad4mModel {
229
229
  * • `null` / empty object — skip ALL relations (used by bare
230
230
  * subscriptions that don't eagerly load relations).
231
231
  */
232
- private takeSnapshot;
232
+ /** @internal */
233
+ protected takeSnapshot(includedRelations?: Record<string, any> | null): void;
233
234
  /**
234
235
  * Returns `true` if any tracked property or relation has changed
235
236
  * since the last hydration (or since `takeSnapshot()` was last called).
@@ -299,13 +300,14 @@ export declare class Ad4mModel {
299
300
  static queryToSPARQL(perspective: PerspectiveProxy, query: Query): Promise<string>;
300
301
  /**
301
302
  * Build the JSON parameters needed for a model query/subscription endpoint.
302
- * Returns the className, queryJson, and shapeJson that the Rust executor expects.
303
+ * Returns the className and queryJson that the Rust executor expects.
304
+ * Shape resolution happens server-side from the perspective's SHACL triples.
303
305
  * @internal
304
306
  */
305
307
  static prepareModelQueryParams(query?: Query, classNameOverride?: string | null): {
306
308
  className: string;
307
309
  queryJson: string;
308
- shapeJson: string;
310
+ metadata: ModelMetadata;
309
311
  };
310
312
  /**
311
313
  * Parse raw model query/subscription result JSON into typed model instances.
@@ -313,21 +315,6 @@ export declare class Ad4mModel {
313
315
  * @internal
314
316
  */
315
317
  static parseModelResult<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, raw: any, include?: IncludeMap, properties?: string[]): T[];
316
- /**
317
- * Resolve non-literal (file-language) properties on an array of already-constructed
318
- * model instances. Handles two cases:
319
- *
320
- * 1. The Rust executor returned a raw URI string → fetch via `getExpression` then apply transform.
321
- * 2. The Rust executor already resolved the expression and returned a `FileData` object
322
- * (happens when the perspective backend eagerly fetches file content) → apply transform
323
- * (or `defaultFileDecode` if no transform is registered on the class, e.g. for SHACL-
324
- * synthesised model classes).
325
- *
326
- * Extracted as a public static so `ModelQueryBuilder.subscribe()` can reuse it without
327
- * duplicating logic or introducing a circular dependency.
328
- * @internal
329
- */
330
- static resolveNonLiteralProps<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, instances: T[]): Promise<void>;
331
318
  /**
332
319
  * Execute a model query via the executor-side endpoint.
333
320
  *
@@ -342,15 +329,14 @@ export declare class Ad4mModel {
342
329
  *
343
330
  * @param perspective - The perspective to search in
344
331
  * @param query - Optional query parameters to filter results
345
- * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
332
+ * @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
333
+ * All queries now use the Rust SPARQL pipeline.
346
334
  * @returns Array of matching models
347
335
  *
348
336
  * @example
349
337
  * ```typescript
350
- * // Get all recipes (uses SPARQL by default)
351
338
  * const allRecipes = await Recipe.findAll(perspective);
352
339
  *
353
- * // Get recipes with specific criteria (uses SPARQL)
354
340
  * const recipes = await Recipe.findAll(perspective, {
355
341
  * where: {
356
342
  * name: "Pasta",
@@ -359,12 +345,9 @@ export declare class Ad4mModel {
359
345
  * order: { createdAt: "DESC" },
360
346
  * limit: 10
361
347
  * });
362
- *
363
- * // Explicitly use Prolog (legacy, for backward compatibility)
364
- * const recipesProlog = await Recipe.findAll(perspective, {}, false);
365
348
  * ```
366
349
  */
367
- static findAll<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, _engine?: 'sparql' | 'prolog' | boolean): Promise<T[]>;
350
+ static findAll<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Q): Promise<(T & IncludeExtras<T, IncludeOf<Q>>)[]>;
368
351
  /**
369
352
  * Finds the first instance matching the query, or `null` if none exists.
370
353
  *
@@ -372,7 +355,7 @@ export declare class Ad4mModel {
372
355
  *
373
356
  * @param perspective - The perspective to search in
374
357
  * @param query - Optional query parameters to filter results
375
- * @param useSPARQL - Whether to use SPARQL (default: true) or Prolog (legacy)
358
+ * @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
376
359
  * @returns The first matching instance, or `null`
377
360
  *
378
361
  * @example
@@ -385,13 +368,13 @@ export declare class Ad4mModel {
385
368
  * }
386
369
  * ```
387
370
  */
388
- static findOne<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, _engine?: 'sparql' | 'prolog' | boolean): Promise<T | null>;
371
+ static findOne<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Q): Promise<(T & IncludeExtras<T, IncludeOf<Q>>) | null>;
389
372
  /**
390
373
  * Gets all instances with count of total matches without offset & limit applied.
391
374
  *
392
375
  * @param perspective - The perspective to search in
393
376
  * @param query - Optional query parameters to filter results
394
- * @param useSPARQL - Whether to use SPARQL (default: true, 10-100x faster) or Prolog (legacy)
377
+ * @param _engine - **Deprecated.** Accepted for backward compatibility but ignored.
395
378
  * @returns Object containing results array and total count
396
379
  *
397
380
  * @example
@@ -401,12 +384,9 @@ export declare class Ad4mModel {
401
384
  * limit: 10
402
385
  * });
403
386
  * console.log(`Showing 10 of ${totalCount} dessert recipes`);
404
- *
405
- * // Use Prolog explicitly (legacy)
406
- * const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
407
387
  * ```
408
388
  */
409
- static findAllAndCount<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query, _engine?: 'sparql' | 'prolog' | boolean): Promise<ResultsWithTotalCount<T>>;
389
+ static findAllAndCount<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Q): Promise<ResultsWithTotalCount<T & IncludeExtras<T, IncludeOf<Q>>>>;
410
390
  /**
411
391
  * Helper function for pagination with explicit page size and number.
412
392
  *
@@ -424,7 +404,7 @@ export declare class Ad4mModel {
424
404
  * console.log(`Page ${page.pageNumber} of recipes, ${page.results.length} items`);
425
405
  * ```
426
406
  */
427
- static paginate<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Query, _engine?: 'sparql' | 'prolog' | boolean): Promise<PaginationResult<T>>;
407
+ static paginate<T extends Ad4mModel, Q extends TypedQuery<T> = {}>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, pageSize: number, pageNumber: number, query?: Q): Promise<PaginationResult<T & IncludeExtras<T, IncludeOf<Q>>>>;
428
408
  /**
429
409
  * Generates a SPARQL COUNT query for the model.
430
410
  *
@@ -449,7 +429,7 @@ export declare class Ad4mModel {
449
429
  * });
450
430
  * ```
451
431
  */
452
- static count(perspective: PerspectiveProxy, query?: Query): Promise<number>;
432
+ static count<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: TypedQuery<T>): Promise<number>;
453
433
  private setProperty;
454
434
  /** Resolve a relation argument to a plain string ID. Accepts either a raw
455
435
  * string ID or an Ad4mModel instance (in which case `.id` is used). */
@@ -651,6 +631,20 @@ export declare class Ad4mModel {
651
631
  * ```
652
632
  */
653
633
  static register(this: typeof Ad4mModel, perspective: PerspectiveProxy): Promise<void>;
634
+ /**
635
+ * Batch-registers multiple model classes on a perspective in a single RPC call.
636
+ * This is significantly faster than calling `register()` on each model individually
637
+ * because it eliminates N-1 round-trips and mutex acquisitions.
638
+ *
639
+ * @param perspective - The perspective to register the models on
640
+ * @param models - Array of Ad4mModel subclasses to register
641
+ *
642
+ * @example
643
+ * ```typescript
644
+ * await Ad4mModel.registerAll(perspective, [Community, Channel, Message, Task]);
645
+ * ```
646
+ */
647
+ static registerAll(perspective: PerspectiveProxy, models: (typeof Ad4mModel)[]): Promise<void>;
654
648
  /**
655
649
  * Executes a set of model operations inside a single batch (transaction).
656
650
  *
@@ -704,7 +698,7 @@ export declare class Ad4mModel {
704
698
  * });
705
699
  * ```
706
700
  */
707
- static query<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: Query): ModelQueryBuilder<T>;
701
+ static query<T extends Ad4mModel>(this: typeof Ad4mModel & (new (...args: any[]) => T), perspective: PerspectiveProxy, query?: TypedQuery<T>): ModelQueryBuilder<T>;
708
702
  /**
709
703
  * Creates an Ad4mModel class from a JSON Schema definition.
710
704
  *